Getting started in a new codebase can be very overwhelming, even more so if you are new to programming. So where do you start? Where are the places to look to learn the most about a codebase? Let’s take a look at few common areas for Laravel.
Project Documentation
Project documentation can be the most helpful when learning a new codebase. You will undoubtedly be luckier if your codebase has documentation, but many times it can be out of date or very sparse. Project documentation is typically in the form of a readme file, wiki, or other shared document on Confluence or Google Docs. While you are working on the new codebase, don’t hesitate to contribute to the current documentation to fill in the gaps, or make something more explicit.
If you are unlucky (and in the majority), your project will not have any documentation at all. A lack of documentation is not entirely a bad thing. If this is the case, you will have the opportunity to write the documentation for your team. You and your teammates will thank you in the future – as well as any new developers you onboard.
Writing documentation indeed isn’t a glamorous job, but it is essential to keep a project thriving. The project documentation not only has an outline of the technologies used and the initial setup, but it should also state the ”whys” and ”hows” of the software which isn’t always clear from the code itself. Certain higher-level decisions and reasons can, and should, be documented to help better understand the codebase.
composer.json
Composer is a PHP package manager that has helped push the PHP ecosystem forward at a rapid pace over the last few years. Laravel has used Composer since version 4, so chances are you have a composer.json file in your project. You should see a composer.json and a composer.lock file in your project repository.
The lock file includes the exact versions of dependencies your app requires in the project, and the JSON file shows a general release of the dependencies. For now, we are only interested in the JSON version, but if you would like to learn more about these files, you can read more here.
While looking through the composer.json file, you will notice a require block, which looks similar to
{ "require": { "php": ">=7.1.3", "fideloper/proxy": "~4.0", "laravel/framework": "5.6.*", "laravel/tinker": "~1.0" }}In this example, we have a project that is requiring Laravel 5.6, as well as two other packages and a minimum PHP version of 7.1.3. You will more than likely have more dependencies in your project, and versions may vary.
Now that you know the dependencies your project requires, you can start looking into what each is and what they do. I would suggest starting with the Laravel dependency, and its documentation. Luckily the documentation is straightforward to find online at https://laravel.com/docs/{VERSION} and https://laravel.com/api/{VERSION}, so for the case above these would be https://laravel.com/docs/5.6 and https://laravel.com/api/5.6.
The docs will give you a general overview of the framework and how each of the major pieces works. The api docs will give you a list of all of the framework’s classes and all of the methods in each class.
Once you have looked through the Laravel documentation, you can then look at each of the other dependencies listed. You can find more information by going to Packagist which is the package repository which Composer uses. You can find more information about each dependency by going to https://packagist.org/packages/{VENDOR}/{PACKAGE} which would look like https://packagist.org/packages/fideloper/proxy.
On each Packagist page, you will get a description of the package, a list of its dependencies, version numbers, a link to the source repository (like GitHub), and the full readme file, amongst other useful information. This page should give you enough information to understand what the package is and what it does for your codebase. Repeat this process for all of the other dependencies in your composer.json file.
Routes
Routes are your map into the application. They give you a direct link from what’s getting requested through the browser to a controller or closure. Once you have found the corresponding controller to a route, you can further dig into what the controller is doing, what other classes it is using, and how it functions. As you work through your application via the browser, repeat this process for each route you come across.
Route files can be found in the following places:
- Laravel 5.3+
routes/*.php - Laravel 5.0-5.2
app/Http/routes.php - Laravel 4.2
app/routes.php
Route “gotchas”
Depending on how the project routes are defined, you might need a few different tactics to find specific URLs accurately.
Let’s take for example the URI /users/123/profile. You might be able to find it by searching for users/{id}/profile. However, this could be included in a route group making it slightly harder to find.
Route::prefix('users')->group(function () { Route::get('{id}/profile', 'UsersController@profile');});In this example users is disconnected from {id}/profile making it harder to find. While this is easy to spot on a few lines, it is significantly harder when your route files have hundreds or thousands of route definitions.
Another example that catches me all the time is Route::resource() (and in newer versions Route::apiResource()).
Route::resource() will automatically generate routes automatically for you given a few parameters. For example, adding Route::resource('dogs', 'DogController'); to your routes file will be the same as defining the following.
Route::group(['prefix' => 'dogs'], function () { Route::get('/', 'DogsController@index')->name('dogs.index'); Route::get('create', 'DogsController@create')->name('dogs.create'); Route::post('/', 'DogsController@store')->name('dogs.store'); Route::get('{id}', 'DogsController@show')->name('dogs.show'); Route::get('{id}/edit', 'DogsController@edit')->name('dogs.edit'); Route::put('{id}', 'DogsController@update')->name('dogs.update'); Route::delete('{id}', 'DogsController@destroy')->name('dogs.destroy');});However, if you try to search for something like dogs/{id}/edit you will come up short because the route gets defined as part of a Route::resource().
Sometimes defining routes via Route::resource() make sense, but I prefer to define every route individually to make each URI more searchable. To learn more about the route resource and resourceful controllers, check out the docs here.
The easiest way to get a complete overview of the routes in your application is an artisan command called route:list:
php artisan route:listThe route:list command provides complete details about each route, including the HTTP method, the URI, the route name, the action (i.e., the controller and method), and any middleware configured for each route.
Service Providers
Service providers are where Laravel’s magic happens and gets referenced. The docs sum up what they are well
Service providers are the central place of all Laravel application bootstrapping. Your own application, as well as all of Laravel’s core services are bootstrapped via service providers.
But, what do we mean by “bootstrapped”? In general, we mean registering things, including registering service container bindings, event listeners, middleware, and even routes. Service providers are the central place to configure your application.
You should look through all of your application’s service providers in the app/providers directory. If there have been any custom additions to the codebase, they should be here. Some things to look for are view composers, macros, and adjusting config values just to name a few.
In older versions of Laravel, like 4.2, you will find similar functionality in the global.php file since at that time service providers were typically only used in packages.
Tests
The codebase’s test suite can potentially show you what the application does and how it should react. It can also give valuable insight as to what the edge cases are within the app as well. However, just like the codebase’s documentation the tests could be non-existent, very minimal, or so outdated that they don’t even run anymore.
Like writing documentation writing tests is a great way to learn the application and improve the codebase at the same time. You could stumble over and fix a few bugs, remove unused code, and maybe add test coverage to a vital class within the application.
Tools
One of the best debugging and investigative tools for Laravel is Laravel Debugbar by Barry vd. Heuvel. It is straightforward to install and will show you everything that is going on within your application – routes and controllers used, database queries and execution times, view data, exceptions, a timeline to see what is executing and when, and so much more. Once you have used this package, you will not want to work on another Laravel application without it.
Wrapping Up
In this post, I have outlined a few ways that you can quickly learn about a new Laravel codebase. This article is by no means an exhaustive list, only a starting point. I encourage you to use these suggestions and see where it can take you. If you have any other hints or tips, I would love to hear about them! Please feel free to reach out on Twitter.
