How do i understand the flow of the source code?

neptronix

Hey all.

I am a php programmer of 10 years and mostly write things in a functional way for speed and ease of maintenance and occasionally dip into OOP when warranted.

I have hacked on phpbb's internals using the phpstorm IDE and found it relatively easy to find out what is going where and what is calling what etc, despite being written in an object oriented way under the symfony framework.

I spent last night looking over the source code of flarum and was rather surprised at how it was constructed. There are 411 php files and each one does very little. Many of them are class definitions with a few getter and setter functions. A lot of things are wrapped in abstractions with little to no indication of what they do on the board.

So to figure out what does what, you need to understand the multiple layers of abstractions and a long chain of class method calls which involves probably opening dozens of files to trace the path.

This has me wondering if there is some better way to navigate the maze than phpstorm. I cannot imagine how a developer could keep in short term or even long term memory all of what is going on under the hood.

I looked over the source code of discourse and found it far more understandable despite not understanding the ruby language whatsoever.

What am i missing? what tools are necessary to understand this level of complexity?

Franz

neptronix Could you share a concrete example, so that we have a place where we can start guiding you a little bit?

luceos

I think knowing more about laravel helps gain traction in our source code too. Most of the patterns used are well known there too.

Although very powerful ioc makes understanding the code base harder. Being able to tie interfaces to implementations helps trace logic.

neptronix

Franz Okay, i'll give you an example.

I'm trying to find out what calls the ability to rename a post.

First hit..
src/Discussion/DiscussionPolicy.php

public function rename(User $actor, Discussion $discussion)
{
if ($discussion->user_id == $actor->id && $actor->can('reply', $discussion)) {
$allowRenaming = $this->settings->get('allow_renaming');

        if ($allowRenaming === '-1'
            || ($allowRenaming === 'reply' && $discussion->participant_count <= 1)
            || ($discussion->created_at->diffInMinutes() < $allowRenaming)) {
            return true;
        }
    }
}

At the top of the file, i see use Flarum\Settings\SettingsRepositoryInterface;
So i open up that file..

namespace Flarum\Settings;

interface SettingsRepositoryInterface
{
public function all();
public function get($key, $default = null);
public function set($key, $value);
public function delete($keyLike);
}

Okay, no idea where these settings are coming from or how the previous file gets them.
OK, the logic to get these is in databasesettingsrepository.php. Now it's apparent where these settings are coming from. fine enough.

Obviously i'm in the wrong place for the logic of renaming a discussion though. So i do a search through the whole system.

The logic is in /src/post/DiscussionRenamedPost.php apparently?
No.. this is a single file that shows whether a post was renamed or not. Why a single file for that?

Okay, time to search again for some kind of rename function.
It's not in /src/event/renamed.php. That just has a constructor in it.
What about discussion/discussion.php?

public function rename($title)
{
if ($this->title !== $title) {
$oldTitle = $this->title;
$this->title = $title;

        $this->raise(new Renamed($this, $oldTitle));
    }
    return $this;
}

Okay, it seems evident this is calling a renamed class to do something.

/src/event/renamed.php

public function __construct(Discussion $discussion, $oldTitle, User $actor = null)
{
$this->discussion = $discussion;
$this->oldTitle = $oldTitle;
$this->actor = $actor;
}

Ok, this looks like it's probably the logic but this functionality is incomplete.
Tracing what triggers say, a form that would allow for the post to be renamed and then the beginning of the chain of events is another matter.

So imagine if this functionality is complete and i have to trace it down through multiple files as someone who doesn't understand the codebase..

What sort of tool would i use to simplify going through the many files that are processed from start to finish?

My only experience with laravel is trying to salvage a failed rewrite of a large LMS done in laravel. It had the chain of events scattered across many files.. about 1000+ 1kb class definitions, but the incomplete system only had 10% of the functionality our Php5.0 era LMS had, which had the model, view, and controller all in one file per page. There were so many layers of classes and abstractions that i could not figure out what was going on, neither could another programmer.

It had me wondering what kind of tools he was using to trace execution or map the whole thing. Perhaps it became too complex for him to handle.. I know he used the sublime text editor... i don't know about any other tools.

We ended up writing the whole codebase off and refactoring the php5.0 LMS all the way up to php7.2 standards, which took 6 months whereas the laravel rewrite went on for 2 years. Hey maybe the programmer was an idiot or something but he sure had a lot of great smaller scale laravel projects under his belt and promised the world with it.

So i never took the time to learn laravel, although everyone is using it now so i really wonder what tools are used to start understanding a new codebase's sequence of events and calls from start to finish.

Toby

Thought I might write out an overview out as it may come in handy for the docs in the future anyway.

We start at index.php, where we define a Flarum Site in terms of directory structure, and set up a Flarum Http\Server to serve it.

In Http\Server, first we boot the site into an App. Depending on whether Flarum has been installed or not, this will be an InstalledApp or the Installer app. Part of this process is instantiating and populating a service container.

Then, we send the Request through the app's RequestHandler. In the case of InstalledApp, this is a middleware pipe that will route the request through a collection of middleware depending on whether it is a request to the forum, admin, or API. The middleware collections for each of these are defined in their respective service providers, such as Forum\ForumServiceProvider.

These middleware collections contain a bunch of middleware that handles errors, sets up a session, and authenticates the user, before dispatching the request to the router. The router routes the request according to the RouteCollection defined in the service providers and populated in routes.php files. Subsequently the request will be passed into a RequestHandler (aka. Controller) which will return a Response to send back to the user.

Most forum routes go to Frontend\Controller which uses a Frontend\HtmlDocumentFactory instance to build an HtmlDocument to render into the response. This HtmlDocument contains appropriate JavaScript to boot up Flarum's single-page application. Admin routes do the same. API routes go to Api\Controller classes which use the tobscure/json-api package to build a JSON-API document as the response.

Toby

neptronix Thanks for the elaboration.

I don't think there's any magic tool that will make tracing through a codebase much easier. Rather, I think understanding the fundamental concepts and design patterns that modern PHP codebases tend to use will allow you to make sense of it all and follow it logically rather than jumping around randomly.

The reason we use abstractions, one class per file, etc. is not to make things complex, but to actually make them simpler to understand, more flexible, maintainable, and testable. @Franz and @luceos might be able to suggest some more recommended reading but my go-to example is the SOLID principles.

In the case of your specific example... are you looking for the code that actually carries out renaming a discussion? Or the code which decides if a user has permission to rename a discussion or not?

Either way, as luceos said, it's always best to start from the beginning – like I did in my previous post Toby. The request to rename a discussion is an API request, to PATCH /api/discussions/ID. You can find this route in Api/routes.php. It is handled by Api\Controller\UpdateDiscussionController. This dispatches an EditDiscussion command which is then handled by Discussion\Command\EditDiscussionHandler. The renaming takes place there.

luceos

When I need to trace an action of flarum into the backend I look at the xhr url called. Check where this is defined and then look for the controller and handler of the command dispatched. I'm on mobile but I'll try to whip up a clarification later.

neptronix

luceos When I need to trace an action of flarum into the backend I look at the xhr url called. Check where this is defined and then look for the controller and handler of the command dispatched. I'm on mobile but I'll try to whip up a clarification later.

Please do!

Toby,
I would have never guessed that the action was happening in an API file.

I have a basic understanding of modern php development methodologies but do not adhere to them since i found that too many layers becomes a problem down the road. My work is in a super large and complex learning management system, and when i have to figure out some part of it i haven't touched for 5 years, it's relatively easy to trace the chain of command because from start to finish, it's 5 files at the absolute most, and correlating files are named such that you can, in most cases, skip a hunt through the code to find out the connections, or just smash dat ctrl-b button in phpstorm.

And now you and the rest of the team are probably thinking this:
http://glasstire.com/wp-content/uploads/2013/01/Dude-thats-just-like-your-opinion-man_zps9268c8a7.jpg

But.. being the lead maintainer, you probably have a lot of the structure in your memory from not only designing it yourself, but also from working on it regularly. As this project scales and time goes on, even you are going to forget what the hell is going on and find yourself in my shoes.

With functionality spread across many files and directories, and laravel's magic in play, it's quite the easter egg hunt though and some kind of mapping tool is really necessary to get on board with helping core development.

I'm not arguing against using high art programming methodologies here. I understand i'm an oddball for not adopting them. I'm just trying to figure out how someone works with them.

For sure, the laravel magic doesn't help!

luceos

Toby This dispatches an EditDiscussion command which is then handled by Discussion\Command\EditDiscussionHandler.

This section is hard to understand because the command handler magically tries to find a Handler for the Command, there is no clear path between the two. There has been discussion to drop that in the future though.

luceos

neptronix Please do!

Actually Toby already did 😊

I'll gladly point you into the right direction whenever you have a concrete problem you'd like solved 😉

ripperdoc

neptronix I can only say I share your sentiment. Laravel seem to have went way too far into abstract territory for its own good. Of course, just my opinion. What could help is a bit more comments / inline docs in the code to get one's bearings.

neptronix

I've been reading about frameworks daily and understand the structure a little bit more but still lacking a debug tool to trace execution.

You guys can't possibly be doing this by hand or using xdebug when the project lists >600 dependencies on github.