Laravel project structure - Deep Dive

Overview - Laravel project structure

What is it?

Laravel project structure is the organized way Laravel arranges files and folders in a web application. It helps developers find and manage code easily by grouping related parts together. This structure includes folders for code, configuration, resources, and more, making the app clear and maintainable.

Why it matters

Without a clear project structure, code becomes messy and hard to fix or improve. Laravel's structure solves this by giving a standard layout that everyone can follow, saving time and reducing mistakes. It makes teamwork smoother and helps apps grow without chaos.

Where it fits

Before learning Laravel project structure, you should know basic PHP and how web apps work. After understanding the structure, you can learn Laravel routing, controllers, views, and database handling to build full apps.

Mental Model

Core Idea

Laravel project structure is like a well-organized toolbox where each drawer holds specific tools for building different parts of a web app.

Think of it like...

Imagine a kitchen where ingredients, utensils, and appliances are stored in separate cabinets and drawers. This order helps you cook efficiently without searching for things. Laravel's project structure does the same for your code.

Laravel Project Structure
┌─────────────────────────────┐
│ app/        (Core code)     │
│ ├─ Http/    (Controllers)   │
│ ├─ Models/  (Data models)   │
│ └─ Console/ (Commands)      │
│ config/     (Settings)      │
│ database/   (Migrations)    │
│ public/     (Web entry)     │
│ resources/  (Views & assets)│
│ routes/     (URL routes)    │
│ storage/    (Logs & cache)  │
│ tests/      (Automated tests)│
└─────────────────────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding the app folder basics

Concept: Learn what the app folder holds and why it is central to Laravel projects.

The app folder contains the main code of your application. Inside, you find subfolders like Http for controllers that handle user requests, Models for data representation, and Console for command-line tasks. This folder is where your app's logic lives.

Result

You know where to write and find the core code that makes your app work.

Understanding the app folder helps you focus on where to build your app's brain and how Laravel separates concerns.

2

Foundation

Role of public and resources folders

Concept: Discover how Laravel separates public files and design assets.

The public folder is the web server's entry point. It holds index.php and assets like images, CSS, and JavaScript that browsers load. The resources folder stores templates (views), raw CSS/JS files, and language files before they are processed.

Result

You understand where to put files that users see and how Laravel manages design resources.

Knowing this separation keeps your app secure and organized by controlling what is publicly accessible.

3

Intermediate

Config and routes folder explained

🤔Before reading on: Do you think configuration files and routes are stored together or separately? Commit to your answer.

Concept: Learn how Laravel organizes settings and URL handling separately.

The config folder contains PHP files that set up app settings like database, mail, and caching. The routes folder holds files defining URL paths and which controller handles them, like web.php for browser routes and api.php for API routes.

Result

You can find and change app settings and control how URLs connect to code.

Separating config and routes makes it easier to manage app behavior and navigation independently.

4

Intermediate

Database and storage folders purpose

🤔Before reading on: Does Laravel store user-uploaded files in the database folder or storage folder? Commit to your answer.

Concept: Understand where Laravel keeps database setup and files generated or uploaded by the app.

The database folder contains migrations that define database tables and seeds for sample data. The storage folder holds logs, cache, and user-uploaded files. It is divided into app, framework, and logs subfolders for organization.

Result

You know where to manage database structure and where files are saved during app use.

Recognizing these folders helps you maintain data integrity and handle file storage properly.

5

Advanced

Tests folder and environment files

🤔Before reading on: Are environment settings stored in the config folder or in separate .env files? Commit to your answer.

Concept: Learn about testing code and managing environment-specific settings.

The tests folder contains automated tests to check your app works correctly. Laravel uses PHPUnit here. Environment files like .env store sensitive info like database passwords and differ per environment (local, production). These are not in config but loaded at runtime.

Result

You can write tests to catch bugs and manage different settings safely for each environment.

Separating environment data from code improves security and flexibility across deployments.

6

Expert

How Laravel autoloads and organizes classes

🤔Before reading on: Does Laravel load all classes at once or only when needed? Commit to your answer.

Concept: Understand Laravel's internal class loading and folder naming conventions.

Laravel uses PSR-4 autoloading via Composer to load classes on demand based on their namespace and folder path. The app folder's namespace matches folder names, so Laravel knows where to find each class without manual includes. This speeds up performance and keeps code clean.

Result

You grasp how Laravel efficiently finds and loads code, enabling modular design.

Knowing autoloading prevents confusion about missing classes and helps structure code for scalability.

7

Expert

Customizing and extending project structure

🤔Before reading on: Can you freely move core folders like app or routes without breaking Laravel? Commit to your answer.

Concept: Explore how to safely customize Laravel's structure and when to do it.

Laravel allows some customization like adding new folders inside app or resources, but core folders like app, routes, and public have fixed roles. Changing their location requires deep config changes and is not recommended. Instead, use namespaces and service providers to extend functionality.

Result

You learn the limits of structure changes and best practices for extending apps.

Understanding these limits helps avoid breaking the framework and keeps upgrades smooth.

Under the Hood

Laravel's project structure works by following PHP standards and conventions. The Composer tool reads the composer.json file to autoload classes based on namespaces matching folder paths. The public folder is the web server root, routing requests to index.php, which boots Laravel. Configuration files are loaded early to set up services. Routes map URLs to controller methods. Storage handles runtime data like logs and cache. This layered approach separates concerns and optimizes performance.

Why designed this way?

Laravel was designed to be easy to learn and powerful. The structure borrows from established PHP standards like PSR-4 to ensure compatibility and predictability. Separating public files from app code improves security. Organizing code by function (controllers, models, views) follows MVC principles, making apps easier to maintain. Alternatives like flat file structures or mixing public and private code were rejected to avoid confusion and security risks.

┌─────────────┐
│ Web Server  │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ public/     │  ← Web root, serves index.php
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ index.php   │  ← Boots Laravel framework
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Laravel Core│
│ (app/,      │
│ config/,    │
│ routes/,    │
│ storage/)   │
└─────────────┘
       │
       ▼
┌─────────────┐
│ Composer    │  ← Autoloads classes by namespace
└─────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Is the public folder safe to store sensitive app code? Commit yes or no.

Common Belief: Some think the public folder can hold any files, including sensitive code.

Reality: The public folder is exposed to the internet and should only contain files meant to be public, like images and index.php.

Why it matters: Putting sensitive code in public risks exposing it to attackers, leading to security breaches.

Quick: Do you think Laravel loads all app classes at startup or only when needed? Commit your answer.

Common Belief: Many believe Laravel loads all classes immediately when the app starts.

Reality: Laravel uses autoloading to load classes only when they are used, improving performance.

Why it matters: Assuming all classes load at once can lead to inefficient code and misunderstanding of performance.

Quick: Can you freely rename or move the routes folder without extra setup? Commit yes or no.

Common Belief: Some think you can rename or move core folders like routes without issues.

Reality: Core folders have fixed locations expected by Laravel; moving them breaks routing unless you deeply reconfigure.

Why it matters: Changing core folder locations without care causes app errors and wasted debugging time.

Quick: Is the .env file part of the config folder? Commit yes or no.

Common Belief: Many believe environment variables are stored inside the config folder files.

Reality: The .env file is separate and loaded at runtime to keep sensitive info out of code repositories.

Why it matters: Mixing environment data with config files risks leaking secrets and complicates deployment.

Expert Zone

1

Laravel's folder namespaces must match exactly for autoloading to work; subtle typos cause hard-to-find errors.

2

The storage folder is often linked to public/storage for user uploads, but this requires running artisan commands to create symbolic links.

3

Tests folder structure mirrors app folder to keep tests organized by feature, which helps maintain large codebases.

When NOT to use

Avoid customizing core folder locations or structure unless you have a very specific need and deep Laravel knowledge. For simpler apps or beginners, stick to the default structure. Alternatives like micro-frameworks or flat PHP scripts may suit very small projects better.

Production Patterns

In production, Laravel projects keep the public folder as the web root for security. Developers use environment files to separate config per server. They organize code in app by domain or feature for clarity. Automated tests in tests folder run in CI pipelines. Storage is configured for cloud or local file systems depending on scale.

Connections

Model-View-Controller (MVC) pattern

Laravel project structure implements MVC by separating models, views, and controllers into distinct folders.

Understanding MVC clarifies why Laravel organizes code this way, improving maintainability and teamwork.

Unix filesystem hierarchy

Both organize files by purpose and access level, like separating public and private data.

Knowing filesystem principles helps grasp why Laravel separates public and app folders for security.

Library autoloading in software engineering

Laravel uses Composer's PSR-4 autoloading standard, a common pattern in modern software to load code on demand.

Recognizing autoloading patterns helps understand efficient code loading beyond Laravel.

Common Pitfalls

#1 Putting sensitive PHP code inside the public folder.

Wrong approach:

Correct approach:

Root cause:

Misunderstanding that public folder is web accessible and should only contain public assets.

#2 Editing config files directly to store passwords instead of using .env.

Wrong approach:

'database.php' => 'password' => 'hardcoded_password',

Correct approach:

'database.php' => 'password' => env('DB_PASSWORD'),
// and set DB_PASSWORD in .env file

Root cause:

Not knowing environment variables separate sensitive data from code.

#3 Renaming or moving the routes folder without updating Laravel's bootstrap files.

Wrong approach:

Moving routes/web.php to routes_new/web.php without config changes.

Correct approach:

Keep routes in routes/ folder or update RouteServiceProvider to new path.

Root cause:

Assuming folder locations are flexible without framework constraints.

Key Takeaways

Laravel project structure organizes code and assets into clear folders to keep apps maintainable and secure.

The app folder holds core logic, public is the web root, and resources contain design files, each with a distinct role.

Composer autoloading links namespaces to folders, enabling efficient code loading and modular design.

Environment variables in .env files keep sensitive data separate from code and vary by deployment.

Respecting Laravel's folder conventions prevents common errors and eases teamwork and scaling.