Project structure, configuration and Artisan

A new Laravel 13 project keeps 33 files of its own in seven folders, and the framework finds every one of them by convention, without a line of setup from you. Every web request, even one for a page that does not exist, enters through one file, and every setting that differs between your laptop and a server comes from one other file, .env.

Here you follow one request from public/index.php to the response, map the folders and the make commands that fill them, carry a setting from .env through a config file into your code, and reproduce the deploy-day bug in which env() returns null. The project is Pathshala, the coaching-centre app created in the install lesson.

Every request enters through public/index.php

Ask the development server for two URLs: /up, the health check that the skeleton defines, and /no-such-page, which nothing defines. Both are answered by Laravel:

from session import serve

# Two requests to the development server: a URL the skeleton defines (/up, its health check) and one that nothing
# defines. Both are answered by Laravel, through public/index.php; only the status code and the path are printed.
serve(
    """
curl -s -o /dev/null -w "%{http_code} /up\\n" http://127.0.0.1:8125/up
curl -s -o /dev/null -w "%{http_code} /no-such-page\\n" http://127.0.0.1:8125/no-such-page
""",
    port=8125,
)

# Terminal 1: start the server
$ php artisan serve --host=127.0.0.1 --port=8125 --no-reload
# Terminal 2: send requests
$ curl -s -o /dev/null -w "%{http_code} /up\n" http://127.0.0.1:8125/up
200 /up
$ curl -s -o /dev/null -w "%{http_code} /no-such-page\n" http://127.0.0.1:8125/no-such-page
404 /no-such-page
# Terminal 1 showed this, then Ctrl+C stopped the server:
   INFO  Server running on [http://127.0.0.1:8125].

  Press Ctrl+C to stop the server

  … /up ............................................... ~ …
  … /no-such-page ..................................... ~ …

/up answered 200 and /no-such-page answered 404, and the server’s own terminal logged both. Neither URL is a file in the project. The web server’s document root is public/, and every path that is not a real file there goes to public/index.php, the front controllerfront controller: The one PHP file that every web request enters through, public/index.php in Laravel. It loads Composer's autoloader, builds the application and hands the request to the framework., which hands the request to Laravel. The file is short, and four of its lines do the work:

from session import run

# The lines of public/index.php that load the framework, the route files bootstrap/app.php wires in, and the
# application's own list of service providers.
run(
    """
grep -n -e require -e handleRequest public/index.php
grep -n -e "web:" -e "commands:" -e "health:" bootstrap/app.php
cat bootstrap/providers.php
""",
    app=True,
)

$ grep -n -e require -e handleRequest public/index.php
10:    require $maintenance;
14:require __DIR__.'/../vendor/autoload.php';
18:$app = require_once __DIR__.'/../bootstrap/app.php';
20:$app->handleRequest(Request::capture());
$ grep -n -e "web:" -e "commands:" -e "health:" bootstrap/app.php
10:        web: __DIR__.'/../routes/web.php',
11:        commands: __DIR__.'/../routes/console.php',
12:        health: '/up',
$ cat bootstrap/providers.php
<?php

use App\Providers\AppServiceProvider;

return [
    AppServiceProvider::class,
];

Line 10 serves the maintenance page while php artisan down is in effect. Line 14 loads Composer’s autoloader, so PHP can find any class by its name. Line 18 runs bootstrap/app.php, which builds the application and names its route files: web for pages, commands for console commands and health: '/up', the URL that answered 200. Line 20 passes the request to the framework, and bootstrap/providers.php lists the app’s own service providers, only AppServiceProvider so far. Step through what happens after line 20, and watch where the 404 left the path:

The order matters for the rest of this module. Configuration is loaded before any provider boots, providers boot before any route is matched, and the web middleware group, with the session and the CSRF check, wraps only the routes of routes/web.php.

Your code lives in app, and every other folder has one job

Before you add anything, list every file that a new project keeps in its working folders. vendor/, where Composer put the 109 packages, storage/, where the framework writes while it runs, and public/ are left out:

from session import run

# Every file a new project keeps in its seven working folders (vendor/, storage/ and public/ are left out).
run(
    """
find app bootstrap config database resources routes tests -type f | sort
find app bootstrap config database resources routes tests -type f | wc -l
""",
    app=True,
)

$ find app bootstrap config database resources routes tests -type f | sort
app/Http/Controllers/Controller.php
app/Models/User.php
app/Providers/AppServiceProvider.php
bootstrap/app.php
bootstrap/cache/.gitignore
bootstrap/cache/packages.php
bootstrap/cache/services.php
bootstrap/providers.php
config/app.php
config/auth.php
config/cache.php
config/database.php
config/filesystems.php
config/logging.php
config/mail.php
config/queue.php
config/services.php
config/session.php
database/.gitignore
database/database.sqlite
database/factories/UserFactory.php
database/migrations/0001_01_01_000000_create_users_table.php
database/migrations/0001_01_01_000001_create_cache_table.php
database/migrations/0001_01_01_000002_create_jobs_table.php
database/seeders/DatabaseSeeder.php
resources/css/app.css
resources/js/app.js
resources/views/welcome.blade.php
routes/console.php
routes/web.php
tests/Feature/ExampleTest.php
tests/TestCase.php
tests/Unit/ExampleTest.php
$ find app bootstrap config database resources routes tests -type f | wc -l
      33

Of the 33 files, only three are PHP classes in app/: the base Controller, the User model and AppServiceProvider. The rest are configuration, routes, database files, views and tests, each in the folder where the framework looks for that kind of file. The table is the map for the rest of this track:

Laravel’s directory guide adds two rules that explain the paths. Composer loads app/ under the App namespace, so app/Models/User.php is the class App\Models\User. And folders such as app/Policies do not exist until a make command first needs them.

Artisan make commands put each new class in its folder

Pathshala groups its students into batches, and a batch needs a model, a table, a controller and more. One ArtisanArtisan: Laravel's command-line tool, run as php artisan inside the project folder. Its commands create files (make:model), show what the app sees (route:list, about) and manage caches (config:cache). command writes the starting file of each:

from session import run

# One make:model with --all, the model it wrote, the seven empty actions of its controller, and the routes after it.
run(
    """
php artisan make:model Batch -a
cat app/Models/Batch.php
grep -n "public function" app/Http/Controllers/BatchController.php
php artisan route:list
""",
    app=True,
)

$ php artisan make:model Batch -a
   INFO  Model [app/Models/Batch.php] created successfully.

   INFO  Factory [database/factories/BatchFactory.php] created successfully.

   INFO  Migration [database/migrations/YYYY_MM_DD_HHMMSS_create_batches_table.php] created successfully.

   INFO  Seeder [database/seeders/BatchSeeder.php] created successfully.

   INFO  Request [app/Http/Requests/StoreBatchRequest.php] created successfully.

   INFO  Request [app/Http/Requests/UpdateBatchRequest.php] created successfully.

   INFO  Controller [app/Http/Controllers/BatchController.php] created successfully.

   INFO  Policy [app/Policies/BatchPolicy.php] created successfully.
$ cat app/Models/Batch.php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;

class Batch extends Model
{
    /** @use HasFactory<\Database\Factories\BatchFactory> */
    use HasFactory;
}
$ grep -n "public function" app/Http/Controllers/BatchController.php
14:    public function index()
22:    public function create()
30:    public function store(StoreBatchRequest $request)
38:    public function show(Batch $batch)
46:    public function edit(Batch $batch)
54:    public function update(UpdateBatchRequest $request, Batch $batch)
62:    public function destroy(Batch $batch)
$ php artisan route:list
  GET|HEAD  / ............................................... routes/web.php:5
  GET|HEAD  storage/{path} storage.local › vendor/laravel/framework/src/Illum…
  PUT       storage/{path} storage.local.upload › vendor/laravel/framework/sr…
  GET|HEAD  up vendor/laravel/framework/src/Illuminate/Foundation/Configurati…

                                                            Showing [4] routes

-a, short for --all, wrote 8 files into 7 folders, and two of the folders, app/Http/Requests and app/Policies, were new. Every path follows from the table above, which is how you can predict where any make command writes. The migration’s name begins with the moment it was created, shown in the recording as YYYY_MM_DD_HHMMSS, and that stamp is the order in which migrations run. The model is an empty class that uses HasFactory, and the controller has the seven resource actions, each with an empty body.

The last command is the one to remember: route:list still shows the same 4 routes. A make command such as this one writes classes from templates and adds no route, so no URL reaches BatchController until you add a route, which the first CRUD lesson does in one line. php artisan make:model --help lists the smaller options: -m for a migration, -f a factory, -s a seeder, -c a controller, -r a resource controller, -R form requests and --policy a policy.

A setting travels from .env through a config file to config()

Pathshala prints a centre code on every receipt, and each centre has its own. The code must not be written into the PHP, yet the app must read it like any other setting. Laravel splits the job between two files. The environment fileenvironment file: The .env file in a Laravel project. It holds the values that differ from one computer to the next, such as the database settings, the debug flag and the application key, and stays out of version control., .env, holds the values that differ between computers. A file in config/ decides which settings exist, which variable feeds each one and what the default is:

<?php

return [

    /*
    |--------------------------------------------------------------------------
    | Centre code
    |--------------------------------------------------------------------------
    |
    | The code printed on Pathshala's receipts. Every centre sets its own
    | CENTRE_CODE in .env; a project without one uses PSH-000.
    |
    */

    'centre_code' => env('CENTRE_CODE', 'PSH-000'),

    /*
    |--------------------------------------------------------------------------
    | Batch size
    |--------------------------------------------------------------------------
    |
    | How many students one batch may hold. Values from .env arrive as
    | strings, so the cast makes it a whole number.
    |
    */

    'batch_size' => (int) env('BATCH_SIZE', 30),

];

The session adds the centre’s line to .env, then reads both settings and the app’s name:

from session import run

# A setting from .env, read through config/pathshala.php (the overlay), then a real environment variable that wins
# over the line in .env.
run(
    """
echo CENTRE_CODE=PSH-042 >> .env
php artisan tinker --execute="var_dump(config('pathshala.centre_code'), config('pathshala.batch_size'), config('app.name'));"
php artisan config:show pathshala
export APP_NAME=Pathshala
php artisan tinker --execute="var_dump(config('app.name'));"
""",
    app=True,
    overlay=("config-file",),
)

$ echo CENTRE_CODE=PSH-042 >> .env
$ php artisan tinker --execute="var_dump(config('pathshala.centre_code'), config('pathshala.batch_size'), config('app.name'));"
string(7) "PSH-042"
int(30)
string(7) "Laravel"
$ php artisan config:show pathshala
  pathshala ..................................................................
  centre_code ........................................................ PSH-042
  batch_size .............................................................. 30
$ export APP_NAME=Pathshala
$ php artisan tinker --execute="var_dump(config('app.name'));"
string(9) "Pathshala"

config('pathshala.centre_code') names the file, then the key, and returned PSH-042 from .env. BATCH_SIZE is set nowhere, so the default applied, and the (int) cast made it int(30). config:show pathshala prints the same two values as the framework resolved them. The last two commands show the rule that surprises people: .env says APP_NAME=Laravel, but a variable that the real environment already holds wins, so after export APP_NAME=Pathshala the app’s name is Pathshala. That is how a server can set values without changing .env.

Without a cast, every .env value reaches the config file as a string, except a few reserved words that the configuration guide lists:

After config:cache, env() outside the config files returns null

A controller that prints receipts reads env('CENTRE_CODE') directly. It works on the laptop. On the server, the deploy runs php artisan config:cache, as Laravel’s deployment guide recommends, and from then on the receipts have no centre code. The session reproduces it with the same config file:

from session import run

# env() and config() before and after config:cache. One tinker reads both values, config:cache writes the cached
# file, about --only=cache reports the state, and the second tinker shows what env() returns once the cache is in
# place.
run(
    """
echo CENTRE_CODE=PSH-042 >> .env
php artisan tinker --execute="var_dump(env('CENTRE_CODE'), config('pathshala.centre_code'));"
php artisan config:cache
php artisan about --only=cache
php artisan tinker --execute="var_dump(env('CENTRE_CODE'), config('pathshala.centre_code'));"
""",
    app=True,
    overlay=("config-file",),
)

$ echo CENTRE_CODE=PSH-042 >> .env
$ php artisan tinker --execute="var_dump(env('CENTRE_CODE'), config('pathshala.centre_code'));"
string(7) "PSH-042"
string(7) "PSH-042"
$ php artisan config:cache
   INFO  Configuration cached successfully.
$ php artisan about --only=cache
  Cache ......................................................................
  Config .............................................................. CACHED
  Events .......................................................... NOT CACHED
  Routes .......................................................... NOT CACHED
  Views ........................................................... NOT CACHED
$ php artisan tinker --execute="var_dump(env('CENTRE_CODE'), config('pathshala.centre_code'));"
NULL
string(7) "PSH-042"

Before the cache, both calls return PSH-042. config:cache writes every value to one file, bootstrap/cache/config.php, and about --only=cache now reports Config as CACHED. After that, env('CENTRE_CODE') is NULL while config('pathshala.centre_code') is still PSH-042. The configuration cacheconfiguration cache: The file bootstrap/cache/config.php that php artisan config:cache writes, with every configuration value already worked out. While it exists, Laravel does not read .env, so env() outside the config files no longer sees its values. also freezes the values when the real environment itself changes:

from session import run

# While the configuration is cached, the real environment and config() keep separate values until config:clear
# removes the cache. The session caches a .env with CENTRE_CODE=PSH-042, then exports CENTRE_CODE=PSH-099 and
# reads both again, then clears the cache and reads them once more.
run(
    """
echo CENTRE_CODE=PSH-042 >> .env
php artisan config:cache
export CENTRE_CODE=PSH-099
php artisan tinker --execute="var_dump(env('CENTRE_CODE'), config('pathshala.centre_code'));"
php artisan config:clear
php artisan tinker --execute="var_dump(env('CENTRE_CODE'), config('pathshala.centre_code'));"
""",
    app=True,
    overlay=("config-file",),
)

$ echo CENTRE_CODE=PSH-042 >> .env
$ php artisan config:cache
   INFO  Configuration cached successfully.
$ export CENTRE_CODE=PSH-099
$ php artisan tinker --execute="var_dump(env('CENTRE_CODE'), config('pathshala.centre_code'));"
string(7) "PSH-099"
string(7) "PSH-042"
$ php artisan config:clear
   INFO  Configuration cache cleared successfully.
$ php artisan tinker --execute="var_dump(env('CENTRE_CODE'), config('pathshala.centre_code'));"
string(7) "PSH-099"
string(7) "PSH-099"

After export CENTRE_CODE=PSH-099, env() sees the new value at once, but config() keeps PSH-042 until config:clear removes the cache. Step through the same requests to see where each value comes from:

The cause is one early return in the framework. LoadEnvironmentVariables, the bootstrapper that loads .env, stops at once when the configuration is cached, so .env is never read and env() sees only the variables of the real environment. The config files ran their env() calls when the cache was built, which is why their values survive. The configuration guide states the rule that follows:

The cache is for servers. The guide says not to run config:cache while you develop, because every change to a setting would then need a new cache, and php artisan optimize caches the configuration, events, routes and views together for a deploy.

Four Artisan commands show what the framework sees

Three questions come up every day: is the route registered, which settings are in force, and what is in the database? Each has a one-line answer, and a fourth command runs a line of PHP inside the app:

from session import run

# Three questions about a project, each answered by one Artisan command: which routes exist, which session settings
# are in force, and which tables the database holds. Then one line of PHP in Tinker.
run(
    r"""
php artisan route:list --except-vendor
php artisan config:show session
php artisan db:show
php artisan tinker --execute="echo App\Models\User::count(), ' users', PHP_EOL;"
""",
    app=True,
)

$ php artisan route:list --except-vendor
  GET|HEAD       / .......................................... routes/web.php:5

                                                            Showing [1] routes
$ php artisan config:show session
  session ....................................................................
  driver ............................................................ database
  lifetime ............................................................... 120
  expire_on_close ...................................................... false
  encrypt .............................................................. false
  files ........................................... storage/framework/sessions
  connection ............................................................ null
  table ............................................................. sessions
  store ................................................................. null
  lottery ⇁ 0 .............................................................. 2
  lottery ⇁ 1 ............................................................ 100
  cookie ..................................................... laravel-session
  path ..................................................................... /
  domain ................................................................ null
  secure ................................................................ null
  http_only ............................................................. true
  same_site .............................................................. lax
  partitioned .......................................................... false
  serialization ......................................................... json
$ php artisan db:show
  SQLite .............................................................. 3.53.4
  Connection .......................................................... sqlite
  Database .......................................... database/database.sqlite
  Host .......................................................................
  Port .......................................................................
  Username ...................................................................
  URL ........................................................................
  Open Connections ...........................................................
  Tables ................................................................... 9

  Schema / Table ........................................................ Size
  main / cache ............................................................. —
  main / cache_locks ....................................................... —
  main / failed_jobs ....................................................... —
  main / job_batches ....................................................... —
  main / jobs .............................................................. —
  main / migrations ........................................................ —
  main / password_reset_tokens ............................................. —
  main / sessions .......................................................... —
  main / users ............................................................. —
$ php artisan tinker --execute="echo App\Models\User::count(), ' users', PHP_EOL;"
0 users

route:list --except-vendor hides the routes that the framework itself registers and leaves the one route of routes/web.php; without the option the list had 4. config:show session prints the session settings as resolved: the database driver and a lifetime of 120 minutes, both set in .env. db:show names the connection and lists 9 tables. The skeleton’s three migrations build eight of them, from users to failed_jobs, and migrations records which migrations have run. TinkerTinker: A prompt opened with php artisan tinker, where each PHP line you type runs inside your loaded application: read a config() value, call a helper or query a model. ran one line against the loaded app and counted 0 users; without --execute, php artisan tinker opens a prompt where you type such lines one after another.

php artisan list shows every command, and php artisan help followed by a command’s name describes it with its options, as make:model --help did above. The install lesson’s php artisan about adds the summary of versions, drivers and caches.

Practise: from the front door to a cached setting

Try these on your own Pathshala project, then take the self-check below, which starts with the idea you have shown least.

1. Run php artisan serve, open /up and a URL that does not exist, and find both requests in the server’s terminal.
2. Before you run php artisan make:model Student -mf, write down the two extra files it will create and their folders. Then compare with its INFO lines.
3. Create config/pathshala.php from this lesson, add CENTRE_CODE to .env and a placeholder to .env.example, and check the value with php artisan config:show pathshala.
4. Run php artisan config:cache, read the value with env() and with config() in Tinker, then run php artisan config:clear, so the cache does not stay on while you develop.

Interview questions

Warm-up (fresher): why does env() return null after php artisan config:cache, and how do you avoid it?

config:cache runs every config file once and writes the results to bootstrap/cache/config.php. While that file exists, the bootstrapper that loads .env returns early, so the variables in .env never reach the process, and env() sees only real environment variables, the ones the server or the shell set. A name that exists only in .env, such as CENTRE_CODE, therefore gives null. Values read through config() are unaffected, because the config files called env() while the cache was built and the results are stored in it. The fix is a rule for the whole codebase: call env() only in config files, and read every setting elsewhere with config('file.key'). Then the cache makes settings faster to load and changes nothing your code sees.

An interviewer who likes that answer often moves on to settings on a live server, with two longer questions:

Key takeaways

• Every web request enters through public/index.php, which loads Composer’s autoloader, builds the app from bootstrap/app.php and hands the request to the kernel’s bootstrappers, the middleware and the router.
• A new project keeps 33 files of its own in seven folders, each folder has one job, and make commands write each new class into the folder for its kind without adding any route.
• .env holds the values that differ between computers, a file in config/ reads them with env() and a default, your code reads the result with config('file.key'), and a real environment variable wins over .env.
• After config:cache, Laravel does not read .env, so env() outside the config files returns null, and later changes wait for config:clear or a new cache.
• route:list, config:show, db:show and Tinker show what the framework actually registered, resolved and stored, so you check instead of guessing.