DEV Community: Anas Hussain

Why Laravel's Service Container Feels Like Magic: Dependency Injection Explained

Anas Hussain — Tue, 14 Jul 2026 05:34:49 +0000

1. Hook & Problem Statement

You’ve been there. You're building a Laravel application, and everything is going smoothly. You type Route::get('/orders', [OrderController::class, 'index']), define your method, and suddenly—you need to send an email.

You type-hint MailerInterface $mailer in your constructor, and boom—it just works. You don't instantiate anything. You don't see a new keyword. It feels like the framework reached into the ether, grabbed the object you needed, and handed it to you.

"How did that get there?" you ask yourself. "Is it voodoo? Is it magic?"

For many developers, the Laravel Service Container remains a black box. It’s the "magic" behind the scenes that we accept, but don't truly understand. This causes a problem: when the magic breaks, you’re left helpless. When you have to write your own services, you default to new and static calls, creating code that is impossible to test and impossible to change.

Today, we’re going to take the wizard hat off the Service Container and look at the engineering underneath. We are going to demystify the magic.

2. Why This Pattern/Concept Exists

Before we can understand the container, we must understand the problem it solves.

The Coupling Catastrophe

Imagine a PaymentProcessor that relies on a StripeAPI class. If you create the Stripe object inside the PaymentProcessor using new StripeAPI(), you have created a tight coupling.

class PaymentProcessor {
    public function __construct() {
        $this->stripe = new StripeAPI(); // Hard dependency
    }
}

The Pain That Existed Before

Before patterns like Dependency Injection (DI) became mainstream, developers faced a "Big Ball of Mud."

Impossible to Test: How do you test the PaymentProcessor without actually charging a credit card? You can't mock StripeAPI because it's hardcoded.
Impossible to Replace: What happens when the business decides to switch from Stripe to PayPal? You have to rip open the PaymentProcessor and rewrite it. This violates the Open/Closed Principle (OCP).
The "Ripple Effect": If StripeAPI requires a new HttpClient in its constructor, you now have to update every single place where you call new StripeAPI().

Why Large Applications Need It

As your application scales, the complexity of object graphs grows. Consider a User Service that needs a Logger, a Mailer, and a Repository. Those dependencies might need their own dependencies.

Manually managing this chain of new statements (new A(new B(new C()))) becomes a maintenance nightmare. The Container solves the problem of managing object construction and lifecycle, allowing you to focus on the business logic rather than the plumbing.

The bottom line: We need a way to ask for what we need, without knowing how to build it. We need to shift the responsibility of building objects to a "factory" of factories.

3. Real World Analogy

The Restaurant
Think of your Laravel Application as a high-end restaurant. You (the Controller) are the waiter. The Kitchen (the Service Container) is in the back.

The Bad Way (No DI): If you, the waiter, had to grow the vegetables, butcher the meat, and bake the bread every time a customer ordered a burger, you would be terrible at your job. You are tightly coupled to the food supply chain.
The DI Way: You walk to the kitchen pass (the Constructor) and say, "I need a Burger with a side of Fries." You don't care which chef makes it, what oven they use, or where the beef came from. You just know that if you ask the kitchen for it, you will receive a prepared item.
Analogy Mapping:
- Waiter (Client): The OrderController.
- The Request (Order): The __construct or __invoke method.
- The Kitchen (Container): The Laravel Service Container.
- The Recipe (Binding): The Service Provider ($this->app->bind).
- The Chef (Factory): The build process that resolves the dependencies.

The kitchen handles the complexity so the waiter can focus on service.

4. The Pain (Bad Design)

Let’s look at a typical "Dependency Hell" situation in a Laravel application.

class PdfExporter
{
    public function export(Invoice $invoice): string
    {
        // 1. Hard dependency on a specific library
        $dompdf = new Dompdf();

        // 2. Hard dependency on the Filesystem to save it
        $path = storage_path('app/invoices/');
        if (!is_dir($path)) {
            mkdir($path, 0777, true);
        }

        $html = view('invoices.pdf', compact('invoice'))->render();
        $dompdf->loadHtml($html);
        $dompdf->render();
        $output = $dompdf->output();
        file_put_contents($path . $invoice->id . '.pdf', $output);

        return $path . $invoice->id . '.pdf';
    }
}

Why is this terrible?

Tight Coupling: PdfExporter is tied to Dompdf. If you want to use Tcpdf, you must change this code.
Testing Nightmare: To unit test this, you must generate a real PDF and write to the file system. Your tests will be slow, fragile, and require disk space.
Violates SRP: This class is doing a lot. It's generating the HTML, saving the file, and generating the PDF.
Magic Strings: The path is hardcoded.

This code is rigid. It cannot be extended, and it is resistant to change.

5. Solution Overview

Dependency Injection is a principle that states: A class should not instantiate its dependencies; it should ask for them.

Core Idea

Instead of a class looking for its dependencies (via new or static calls), it receives them from the outside.

Main Participants

The Client: The class that needs a service (e.g., PdfExporter).
The Dependencies: The services the client needs (e.g., PdfInterface, FileSystemInterface).
The Injector: The entity that creates the dependencies and passes them to the client (e.g., the Laravel Service Container).

Mental Model

Think of the __construct method as a contract. It is a promise: "If you (the Container) give me these objects, I will handle the rest." You write your code to be handed objects, rather than hunting for them.

Benefits

Loose Coupling: Your class only depends on the interface, not the implementation.
High Testability: You can pass "Mock" objects into the constructor easily.
Code Reusability: The dependency can be swapped out for different environments.

Trade-offs

Abstraction Overhead: You will have more interfaces and classes.
Indirection: It's sometimes harder to trace where an implementation is coming from.

6. UML Diagram

Laravel Service Container Architecture

Explanation: The Container is aware of ConcreteDependencyA and ConcreteDependencyB. The Client only knows about the DependencyInterface. The Container injects the correct concrete implementation into the Client at runtime.

7. Vanilla PHP Example

Let's refactor the PdfExporter using pure PHP 8+ syntax to show the power of DI.

Before Refactoring

(As seen in the "Pain" section—hardcoded Dompdf, file paths, etc.)

After Refactoring

Step 1: Define Interfaces (The Contract)

interface PdfGeneratorInterface
{
    public function generate(string $html): string; // returns PDF binary string
}

interface FileStorageInterface
{
    public function save(string $path, string $content): bool;
}

Step 2: Create Implementations

class DompdfGenerator implements PdfGeneratorInterface
{
    public function __construct(
        private array $options = [] // configuration passed via constructor
    ) {}

    public function generate(string $html): string
    {
        $dompdf = new \Dompdf\Dompdf($this->options);
        $dompdf->loadHtml($html);
        $dompdf->render();
        return $dompdf->output();
    }
}

class LocalFileStorage implements FileStorageInterface
{
    public function __construct(
        private string $basePath
    ) {}

    public function save(string $path, string $content): bool
    {
        $fullPath = rtrim($this->basePath, '/') . '/' . ltrim($path, '/');
        $directory = dirname($fullPath);
        if (!is_dir($directory)) {
            mkdir($directory, 0777, true);
        }
        return file_put_contents($fullPath, $content) !== false;
    }
}

Step 3: The Refactored Client

class PdfExporter
{
    // Dependency Injection via Constructor Promotion (PHP 8)
    public function __construct(
        private readonly PdfGeneratorInterface $pdfGenerator,
        private readonly FileStorageInterface $fileStorage
    ) {}

    public function export(Invoice $invoice): string
    {
        $html = view('invoices.pdf', compact('invoice'))->render();
        $pdfContent = $this->pdfGenerator->generate($html);

        $path = "invoices/{$invoice->id}.pdf";
        $this->fileStorage->save($path, $pdfContent);

        return $path;
    }
}

Step 4: The Manual Injector (The "Container")

// This is essentially what Laravel does for you.
$generator = new DompdfGenerator(['isRemoteEnabled' => true]);
$storage = new LocalFileStorage(storage_path('app'));

$exporter = new PdfExporter($generator, $storage);
$exporter->export($invoice);

What did we improve?

Testability: In a test, we can pass a MockPdfGenerator that returns a dummy string without hitting the file system or the PDF library.
Open/Closed: If we need a TcpdfGenerator, we just implement the interface. We don't touch PdfExporter.
Single Responsibility: Each class has one job.

8. Laravel Internal Example

Where does Laravel use this? Everywhere.

The HTTP Kernel

Have you ever looked inside app/Http/Kernel.php? It handles middleware.
When a Request comes in, the Kernel resolves the Router and the ControllerDispatcher. It doesn't new them; it asks the container for them.

The `handle` Method in Controllers

Laravel doesn't just resolve Controllers; it resolves the parameters inside them.

class InvoiceController {
    public function show(InvoiceRepository $repo, int $id) { ... }
}

When Laravel routes to this controller, it looks at the method signature. It uses the Container to build InvoiceRepository (and all its sub-dependencies) and injects them, alongside the primitive $id.

Service Providers

Service Providers are the central location for "Binding" things into the container. This is how we tell the container which concrete class to use when an interface is requested.

// In a Service Provider
public function register(): void
{
    $this->app->bind(PdfGeneratorInterface::class, DompdfGenerator::class);
}

This is the "recipe" that tells the container: "When someone asks for PdfGeneratorInterface, give them DompdfGenerator."

9. Real Laravel Application Example

Let's build a Payment Gateway System for an e-commerce app.

Scenario: You support Stripe and PayPal. The business logic (like processing the cart) should not care which gateway is used.

Step 1: The Interface

namespace App\Contracts\Payment;

interface PaymentGatewayInterface
{
    public function charge(array $customerData, float $amount): array;
    public function refund(string $transactionId, float $amount): bool;
}

Step 2: Concrete Implementations

namespace App\Services\Payment;

use App\Contracts\Payment\PaymentGatewayInterface;

class StripeGateway implements PaymentGatewayInterface { ... }

class PayPalGateway implements PaymentGatewayInterface { ... }

Step 3: The Controller

namespace App\Http\Controllers;

use App\Contracts\Payment\PaymentGatewayInterface;

class CheckoutController extends Controller
{
    public function __construct(
        private readonly PaymentGatewayInterface $paymentGateway
    ) {}

    public function store(Request $request)
    {
        // The controller uses the interface.
        // It doesn't know if it's Stripe or PayPal.
        $result = $this->paymentGateway->charge(
            $request->only(['email', 'amount']),
            $request->amount
        );

        return response()->json($result);
    }
}

Step 4: Binding in a Service Provider

namespace App\Providers;

use App\Contracts\Payment\PaymentGatewayInterface;
use App\Services\Payment\StripeGateway;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // Magic! We bind the interface to the concrete class.
        // Now, whenever a controller asks for PaymentGatewayInterface,
        // it gets StripeGateway.
        $this->app->bind(PaymentGatewayInterface::class, StripeGateway::class);
    }
}

Now, if the business wants to switch to PayPal for a specific country, you can use Contextual Binding in the service provider, or update a single line in the Service Provider. The Controller is clean and unbothered.

10. SOLID Principles Mapping

Dependency Injection is the enabler of SOLID.

D - Dependency Inversion Principle (DIP):
This is the big one. DI enforces DIP. High-level modules (CheckoutController) should not depend on low-level modules (StripeGateway). Both should depend on abstractions (PaymentGatewayInterface). DI is the mechanism that makes this physical separation possible.
O - Open/Closed Principle (OCP):
The CheckoutController is closed for modification (we don't touch it) but open for extension (we can add PayPalGateway and change the binding). The container makes this extension pluggable.
S - Single Responsibility Principle (SRP):
By injecting dependencies, we force classes to focus on their core job. The CheckoutController handles HTTP requests. The StripeGateway handles API calls. If we instantiated dependencies with new, the controller would be responsible for knowing the Stripe API key, which violates SRP.
L - Liskov Substitution Principle (LSP):
The container relies on this. Since StripeGateway and PayPalGateway implement the same interface, they are substitutable for each other. The controller (which uses the interface) will work correctly regardless of which one is passed in.

11. Trade-offs

Benefits

Flexibility: You can swap implementations by changing a single line in a Service Provider.
Testability: The ability to mock dependencies is the single greatest benefit to unit testing.
Decoupled Architecture: Changes to one part of the system are less likely to break another part.

Costs

Indirection: It is harder to follow the "flow" of code. You see a PaymentGatewayInterface and have to figure out which concrete class is bound to it.
Overhead: You create more files (interfaces, service providers, DTOs). For tiny, one-off scripts, this might be overkill.
Complexity: If you are using the Service Container heavily, you need to understand features like Contextual Binding, Tags, and Service Providers to debug effectively.

When is it justified?

You should use DI when you are building logic that is likely to change (e.g., business rules, external integrations) or when you need to unit test the class.

12. When NOT To Use It

3 Green Flags (USE IT)

External Services: You are integrating with an external API (e.g., Mailchimp, AWS S3).
Persistence Layer: You need to interact with a database or cache.
Business Logic: You have complex domain logic that requires extensive unit testing.

3 Red Flags (AVOID IT)

Data Transfer Objects (DTOs): A DTO usually holds simple, typed data (e.g., UserInput). It rarely needs dependencies. Autowiring a DTO is usually overkill.
Tiny Scripts: For a simple Artisan command that merely clears a cache, using a straight Cache::flush() (Facade) is much faster and easier than injecting a contract.
Controllers with Primitive Types: Sometimes a controller just needs a $request or a $userId. Laravel handles this, but don't create a service class just to inject an int.

13. Common Mistakes

1. Overengineering (The "Just in Case" Syndrome)

"I might need to switch from MySQL to Postgres, so I'll define an interface!"
While a valid concern, many developers prematurely abstract simple CRUD operations. Only create the abstraction when you actually have two implementations, or you specifically need it for mocking. YAGNI (You Ain't Gonna Need It) applies here.

2. Confusing Service Providers with Business Logic

Putting business logic inside boot() or register() methods of Service Providers.

// BAD: Service Provider doing business logic
public function boot() {
    $user = User::first(); // NO! This runs on every request!
}

Service Providers are only for registering services. boot() should only run registration logic (e.g., Route::macro, Gate::define).

3. Using the Container as a Service Locator

// The "Service Locator" Anti-Pattern
class OrderService {
    public function process(Order $order) {
        $payment = app(PaymentInterface::class); // BAD!
    }
}

You are calling app() inside the class. This hides the dependency. The class is no longer "self-documenting" via its constructor. Always use Constructor Injection.

4. Not Providing Default Values

If you don't bind an interface in the Service Provider, Laravel will try to instantiate the interface directly and fail with a binding error.
Always ensure your bindings exist in the register() method.

14. Frequently Asked Interview Questions

Beginner/Intermediate

Q: What is Dependency Injection? A: It is a design pattern where a class receives its dependencies from an external source rather than creating them internally.
Q: How does Laravel know what to inject when I type-hint an interface? A: Laravel uses the Service Container. You must define a binding in a Service Provider (usually AppServiceProvider) that tells the Container which concrete class to use for that interface.
Q: What is the difference between bind and singleton in the Service Container? A: bind creates a new instance every time it is resolved. singleton resolves the instance once and reuses that same instance for the rest of the request lifecycle.
Q: Is dependency injection the same as the Service Container? A: No. Dependency Injection is the pattern (how to structure code). The Service Container is the tool (a helper) that automates the injection process in Laravel.

Senior/Architect

Q: Explain the difference between Constructor Injection, Setter Injection, and Method Injection. Which is preferred and why? A: Constructor Injection (dependencies in __construct) is preferred because it ensures the object is in a valid state after instantiation. Setter Injection allows optional dependencies to be set later, but it can lead to "temporal coupling" (where the object is partially built). Method Injection passes dependencies directly into a specific method, useful for runtime variations (e.g., a payment method).
Q: How would you handle auto-resolving dependencies for dependencies that have primitive arguments (like a $apiKey)? A: You use Contextual Binding in a Service Provider ($this->app->when(Service::class)->needs('$apiKey')->give('value')) or use a Factory Pattern to build the object.
Q: How does Laravel's Container handle circular dependencies? A: By default, it will throw a LogicException (Circular dependency detected). The container cannot build a class that requires itself (e.g., A requires B, B requires A).
Q: What are the performance implications of using the Container heavily? A: Reflective resolution (auto-discovery) is slower than hardcoded new statements. However, Laravel caches the resolved bindings using php artisan optimize, which turns the resolution into an array lookup, mitigating most performance issues.

15. Interactive Practice Challenge

You are a developer on a team building a SaaS application. You have inherited the following code. It works, but it's fragile and impossible to test.

Your Task: Refactor this code to use Dependency Injection. Define the necessary interfaces, create implementation classes, and update the Service Provider.

The Requirement:
We need to send a welcome email when a user registers. The UserRegistrationService uses the SendGridEmail library directly. It also interacts with the User model directly using an Eloquent static call.

// BAD CODE
use App\Models\User;
use SendGrid\Mail\Mail;

class UserRegistrationService
{
    public function register(array $data): User
    {
        // Validates that email is unique
        if (User::where('email', $data['email'])->exists()) {
            throw new \Exception('User already exists');
        }

        // Creates the user
        $user = User::create([
            'name' => $data['name'],
            'email' => $data['email'],
            'password' => bcrypt($data['password']),
        ]);

        // Sends welcome email via SendGrid
        $email = new Mail();
        $email->setFrom("admin@example.com", "Admin");
        $email->setSubject("Welcome!");
        $email->addTo($user->email, $user->name);
        $email->addContent("text/html", "Hello {$user->name}");

        $sendgrid = new \SendGrid(getenv('SENDGRID_API_KEY'));
        $response = $sendgrid->send($email);

        if ($response->statusCode() !== 202) {
            \Log::error('Failed to send welcome email', ['user' => $user->id]);
        }

        return $user;
    }
}

Think about: How would you test this? How would you swap the email service for Mailgun? How would you mock the database check?

(We won't provide the solution here—put your Senior Engineer hat on and refactor it!)

16. Final Mental Model

To keep it simple, memorize these three sentences:

One-sentence definition: Dependency Injection is the design principle where a class asks for what it needs (via its constructor) rather than looking for it itself.
One-sentence intuition: Stop building your tools inside the factory; bring the tools to the worker.
One-sentence decision rule: If a class has logic that is hard to test or likely to change, pull that logic out and inject it; otherwise, keep it simple.

17. Related Concepts

SOLID Principles: Dependency Injection is the practical implementation of the Dependency Inversion Principle (DIP). It works in tandem with Open/Closed to allow extension.
Design Patterns:
- Factory Pattern: Often used alongside DI. A Factory creates complex objects, while DI uses the Factory to provide the object.
- Strategy Pattern: DI is how you inject the specific Strategy into the Context.
- Observer Pattern: The Event system in Laravel uses the Container to resolve listeners.
Laravel Internals:
- Service Providers: The configuration layer where you register bindings.
- Facades: The "light switch" to the container.
- Eloquent Models: While Eloquent doesn't strictly rely on DI for its core, you can inject Repository interfaces into your controllers to abstract Eloquent's query builder.
Enterprise Patterns:
- Inversion of Control (IoC): DI is a subset of the IoC principle. The framework (Container) takes over the control of object lifecycle.

Clean Architecture: Dependency Injection Practice Labs

Dependency Inversion Principle (DIP)

Anas Hussain — Wed, 08 Jul 2026 05:44:07 +0000

The Dependency Inversion Principle (DIP) is the final "D" in SOLID. It states two critical rules:

High-level modules should not depend on low-level modules. Both should depend on abstractions.
Abstractions should not depend on details. Details should depend on abstractions.

In simple terms: Your core business logic should not rely on specific tools or external technologies. Instead, both your logic and your tools should rely on a common blueprint (Interface).

The Real-World Example: Imagine you buy a brand-new smartphone

The Bad Design (Tight Coupling): Imagine if the phone manufacturer hardwired the charging cable directly inside your home's living room wall outlet. Your phone would charge perfectly in that one spot. But if you went to a coffee shop, or if you moved to a new house, your phone would be completely useless because it is tightly coupled to one specific wall.
The Good Design (Dependency Inversion): The smartphone manufacturer and the house architect agree on a common abstraction: the USB-C port.
The phone doesn't care if the power comes from a wall socket, a laptop port, an airplane seat, or a portable power bank.
It only depends on the shape of the USB-C contract. You can swap the power source instantly without modifying your phone.

❌ The Wrong Way: Depending directly on low-level tools (Violates DIP)

Here, the high-level NotificationManager depends directly on a specific low-level tool (MySQLDatabase).

class MySQLDatabase {
    public function saveLog($message) {
        echo "Saving log to MySQL database: $message\n";
    }
}

class NotificationManager {
    private $database;

    public function __construct() {
        // ❌ Tightly coupled! High-level class directly instantiates the low-level class.
        $this->database = new MySQLDatabase(); 
    }

    public function sendAlert($message) {
        // Sending alert logic...
        $this->database->saveLog($message);
    }
}

The Problem: If your company decides to switch from MySQL to MongoDB or Firebase next week, you are forced to open up and completely rewrite your NotificationManager class, risking bugs in your alert system.

✅The Right Way: Inverting the dependency (Adheres to DIP)

We introduce an interface (the USB-C port) between the high-level class and the low-level tool. Both now look up to the abstraction.

Step 1: Create the Abstraction (The Blueprint)

interface LoggerInterface {
    public function log(string $message): void;
}

Step 2: Make low-level tools adapt to the blueprint

class MySqlLogger implements LoggerInterface {
    public function log(string $message): void {
        echo "Saved to MySQL: $message\n";
    }
}

class MongoDbLogger implements LoggerInterface {
    public function log(string $message): void {
        echo "Saved to MongoDB: $message\n";
    }
}

Step 3: Inject the abstraction into the high-level class

The NotificationManager now only knows about the interface. It has no idea (and does not care) what database is being used behind the scenes.

class NotificationManager {
    // Rely completely on the Abstraction (Interface)
    public function __construct(
        private LoggerInterface $logger
    ) {}

    public function sendAlert($message) {
        // Sending alert logic...
        $this->logger->log($message);
    }
}

Why this helps you

Effortless Tech Swaps: You can change your database, payment gateway, or email provider by changing a single line of setup code, without touching your main business logic.
Flawless Testing: You can pass a fake "MockLogger" into the NotificationManager during automated testing so your tests run lightning fast without actually writing data to a real database.
Loose coupling: Reduces dependencies between modules, making the code more flexible and easier to test.
Flexibility: Enables changes to implementations without affecting clients.
Maintainability: Makes code easier to understand and modify.

The main reason 90% of engineers fail to use the Dependency Inversion Principle (DIP) is that they confuse it with Dependency Injection (DI).
They think that by passing a class into a constructor __construct($mysqlDatabase), they are applying DIP. They aren't. Passing a concrete, specific class into another class is just Dependency Injection. DIP requires an Interface (an abstraction) to step in and flip the ownership of the relationship.
Here is how to clear up the confusion and make definitive, master-level architectural decisions.

The 3 Main Confusions Cleared Up

1. Confusion: "Is Dependency Inversion the same thing as Dependency Injection?"

Reality: No. They are entirely different concepts that work together:
Dependency Injection (DI) is a technique for passing a tool into a class (e.g., passing a key into a lock instead of making the lock build its own key).
Dependency Inversion (DIP) is an architectural goal that states high-level policies should not depend on low-level details. You use DI to achieve DIP.

2. Confusion: "Does DIP mean every single new keyword in PHP is a sin?"

Reality: No. This confusion leads to massive over-engineering. You do not need interfaces for raw data objects, entities, or value objects (like new User(), new DateTime(), or new Collection()). You only apply DIP to Services and Infrastructure—classes that perform tasks or talk to external resources (like databases, APIs, file systems, and payment gateways).

3. Confusion: "Who actually owns the interface?"

Reality: In traditional programming, the low-level database or API team defines the structure, and the business logic has to match it. DIP completely inverts this. The high-level business logic defines what it needs, and the low-level database adapters must bend to fit that shape.

The Ultimate DIP Clean Code Check

You are violating DIP if you see your high-level controllers or business services look like this:

class OrderController {
    public function checkout() {
        // ❌ Direct concrete instantiation. 
        // This controller is trapped inside Stripe's ecosystem forever.
        $payment = new StripePaymentGateway(); 
        $payment->charge();
    }
}

The 3-Step Decision Matrix (How to Choose)

When deciding whether to create an abstraction line for a class in PHP, use this mental map:

START DIP_Design_Check

    IF Class_Talks_To_External_Resources_Outside_RAM IS True THEN

        IF Tool_Belongs_To_External_Vendor_Or_Package IS True THEN
            EXECUTE Apply_DIP_Wrap_In_Interface_Immediately

        ELSE
            IF Highly_Likely_To_Change_Tools IS True THEN
                EXECUTE Apply_DIP_Interface
            ELSE
                EXECUTE Direct_Type_Hint_Is_Fine
            END IF
        END IF

    ELSE
        IF Is_Core_Business_Entity IS True THEN
            EXECUTE Do_NOT_Use_DIP_Instantiate_Safely_With_New
        ELSE
            EXECUTE Leave_It_Alone
        END IF

    END IF

END DIP_Design_Check

The "Boundary" Rule: If a class crosses the boundary of your application to talk to the outside world (a payment provider, an SMS gateway, Amazon S3 storage), always apply DIP. Create an interface.
The "Volatile Dependency" Test: Ask yourself: "If this software package or vendor shuts down tomorrow, goes bankrupt, or triples their prices, how many files do I have to rewrite?" If the answer is more than one config or provider file, your system lacks Dependency Inversion.
The Mockability Factor: When writing unit tests, do you need to avoid hitting a live server (like preventing a real charge on a credit card)? If yes, you need an interface so you can swap the real service with a MockPaymentGateway during your test sweeps.

Summary for Decision Making

High-level modules (Controllers, Domain Use Cases, Business Logic) contain the identity and rules of your app.
Low-level modules (MySQL, Redis, AWS, Twilio, Stripe) are merely utility workers.

Refference
Wikepedia

The Laravel Blueprint: Mastering DIP (example)

Let's look at how a Junior developer tightly couples their code to a specific tool, and how a Laravel Master uses Contracts to execute Dependency Inversion.

❌ The Junior Approach (Violates DIP)

Imagine your Laravel application needs to upload user avatars to Amazon S3. A junior developer injects the concrete S3 client directly into a service.

namespace App\Services;

use Aws\S3\S3Client; // ❌ Tightly coupled to Amazon's official SDK!

class ProfileAvatarService
{
    protected $s3;

    public function __construct()
    {
        // ❌ The high-level service creates its own low-level tool.
        $this->s3 = new S3Client([
            'version' => 'latest',
            'region'  => 'us-east-1'
        ]);
    }

    public function updateAvatar($user, $file)
    {
        // Concrete Amazon-specific method execution
        $this->s3->putObject([
            'Bucket' => 'my-avatars',
            'Key'    => "avatars/{$user->id}.jpg",
            'Body'   => fopen($file, 'r')
        ]);
    }
}

Why this fails Laravel Mastery: Your app is trapped in AWS. If your company moves to Google Cloud Storage or DigitalOcean Spaces to save money, you have to find every file referencing S3Client, delete the code, and completely rewrite your upload logic.

The Laravel Mastery Approach (Adheres to DIP)

Laravel handles this using its native Storage Contracts (Illuminate\Contracts\Filesystem\Filesystem). Your high-level business code only talks to the contract. The infrastructure tools (S3, local disk, SFTP) are forced to adapt to what the contract demands.

Step 1: Depend entirely on the Abstraction

Your service doesn't know about Amazon, Google, or local hard drives. It only knows about the Laravel Filesystem contract.

namespace App\Services;

// We import the standard abstract Contract, NOT a concrete SDK package!
use Illuminate\Contracts\Filesystem\Filesystem;

class ProfileAvatarService
{
    // Laravel's Service Container automatically injects the active driver here
    public function __construct(
        protected Filesystem $storage
    ) {}

    public function updateAvatar($user, $file)
    {
        // The common "HDMI plug" method that works on ANY storage system
        $this->storage->put("avatars/{$user->id}.jpg", file_get_contents($file));
    }
}

Step 2: Swap the low-level details in .env

Because both your service and Laravel's drivers depend on the same underlying abstraction, you don't need to change a single line of PHP code to swap out the technology. You just update your configuration or your environment file:

# Switch from Amazon S3 to Local Storage instantly without breaking the app:
FILESYSTEM_DISK=s3
# FILESYSTEM_DISK=local
# FILESYSTEM_DISK=gcs

Step 3: How Laravel wires it up under the hood

If you ever build a custom storage solution (like a custom database-driven file system), you register it in a Service Provider using the Service Container:

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Illuminate\Contracts\Filesystem\Filesystem;
use App\Services\CustomDatabaseStorageDriver;

class StorageServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // Tell Laravel: Whenever a class asks for the Filesystem Contract,
        // hand them our custom driver implementation.
        $this->app->bind(Filesystem::class, function ($app) {
            return new CustomDatabaseStorageDriver();
        });
    }
}

Why this makes you a Laravel Master

Seamless Testing: When writing a feature test for uploading an avatar, you can call Storage::fake('avatars'). Laravel instantly swaps the real storage engine with an in-memory virtual disk. Your tests execute instantly, and you never accidentally upload junk test images to a live Amazon S3 account.
Plugin Architecture: Your application becomes modular. You can change your cache systems, database engines, mail dispatchers, and queue runners on the fly because your controllers and services only interact with framework contracts.

Interface Segregation Principle (ISP)

Anas Hussain — Mon, 06 Jul 2026 07:56:11 +0000

The interface segregation principle (ISP) states that no code should be forced to depend on methods it does not use. ISP splits interfaces that are very large into smaller and more specific ones so that clients will only have to know about the methods that are of interest to them. Such shrunken interfaces are also called role interfaces. ISP is intended to keep a system decoupled and thus easier to refactor, change, and redeploy.

In simple terms: Keep your interfaces small, specific, and focused. It is much better to have many tiny, specialized interfaces instead of one giant "fat" interface that forces classes to write useless code.

Importance in object-oriented design: Within object-oriented design, interfaces provide layers of abstraction that simplify code and create a barrier preventing coupling to dependencies. A system may become so coupled at multiple levels that it is no longer possible to make a change in one place without necessitating many additional changes. Using an interface or an abstract class can prevent this side effect.

The Real-World Example: Imagine you want to sign up for a local fitness center.

The Giant Interface (Violates ISP): The gym only offers a single "$500/month Ultimate Platinum VIP Pass." This pass includes access to the weight room, the swimming pool, the golf simulator, the childcare center, and the juice bar.
The Problem: You just want to lift weights for 30 minutes. However, you are forced to pay for, carry a card for, and sign waivers for the swimming pool and childcare center, even though you don't swim and don't have kids.
The Segregated Interface (Adheres to ISP): The gym splits its services. You buy a "Weight Room Only Pass." Parents buy a "Childcare Pass." Swimmers buy a "Pool Pass." You only interact with, pay for, and use exactly what you need.

❌ The Wrong Way: The "Fat" Interface (Violates ISP)

Imagine an interface for handling corporate office employees.

interface Employee {
    public function codeSoftware();
    public function manageTeam();
    public function cleanBuilding();
}

If you try to create a Developer class using this interface, you run into a major problem. Developers don't clean buildings or manage teams. You are forced to write useless filler code just to satisfy the PHP compiler.

class Developer implements Employee {
    public function codeSoftware() {
        echo "Writing clean code...\n";
    }

    // ❌ Violates ISP! Forced to implement a method they don't use
    public function manageTeam() {
        return null; 
    }

    // ❌ Violates ISP! Forced to write useless code
    public function cleanBuilding() {
        throw new Exception("I am a programmer, not a janitor!");
    }
}

✅The Right Way: Small, Focused Interfaces (Adheres to ISP)

To fix this, break the giant Employee interface into tiny, atomic pieces based on actual actions.

interface Codeable {
    public function codeSoftware();
}

interface Manageable {
    public function manageTeam();
}

interface Cleanable {
    public function cleanBuilding();
}

Now, your PHP classes can cleanly pick and choose exactly which contracts apply to them. No wasted code, no dummy methods, and no fake exceptions.

// The Developer class only cares about coding
class Developer implements Codeable {
    public function codeSoftware() {
        echo "Writing clean code...\n";
    }
}

// A Tech Lead class can do both coding and managing
class TechLead implements Codeable, Manageable {
    public function codeSoftware() { echo "Writing code...\n"; }
    public function manageTeam() { echo "Leading the standup meeting...\n"; }
}

// The Janitor class only cares about cleaning
class Janitor implements Cleanable {
    public function cleanBuilding() {
        echo "Mopping the floors...\n";
    }
}

Why this helps you

Decoupling: Reduces dependencies between classes, making the code more modular and maintainable.
Flexibility: Allows for more targeted implementations of interfaces.
Avoids unnecessary dependencies: Clients don't have to depend on methods they don't use.

The main reason 90% of engineers fail to use the Interface Segregation Principle (ISP) is that they confuse a functional code structure with a business role structure. They create interfaces based on nouns (like interface User or interface Order) instead of behaviors (like CanBeSaved or CanBeEmailed).
This creates massive, bloated contracts that force developers to write empty, useless methods just to satisfy the PHP compiler. Here is how to clear up the confusion and make effortless, high-utility design decisions.

The 3 Main Confusions Cleared Up

1. Confusion: "Does ISP mean I can only have one method per interface?"

Reality: No. An interface can have multiple methods, as long as every single class that implements it needs every single method.
Example: A Cacheable interface might need both get($key) and set($key, $value). They belong together because you cannot practically use a cache that only lets you read but never write.

2. Confusion: "If I have 50 small interfaces, won't my codebase become a mess?"

Reality: It actually makes your codebase much cleaner. In PHP, a single class can implement an unlimited number of interfaces (class User implements Authenticatable, Sluggable, Billable). This is highly flexible, modular, and self-documenting.

3. Confusion: "Can't I just use PHP Traits instead of splitting interfaces?"

Reality: Traits share implementation code (how things work), while interfaces define architectural architectural contracts (what things do). Traits do not solve type-hinting issues. If a controller expects a giant, bloated interface, a Trait won't prevent a developer from calling a method that shouldn't be there.

The Ultimate ISP Smell Test

You are violating ISP if you look at a PHP class and find yourself doing this:

class GuestUser implements FullUserInterface {
    public function getPassword() {
        // ❌ ISP Violation Smell! 
        // Guest users don't have passwords, but the interface forces me to write this.
        return null; 
    }
}

If you ever write return null;, return false;, or throw new Exception("Not implemented"); inside a method required by an interface, your interface is too fat.

The 3-Step Decision Matrix (How to Choose)

When defining a new contract or refactoring an existing one in PHP, use this mental map to ensure ISP compliance:

START ISP_Design_Check

    IF Interface_Named_After_Noun IS True THEN
        EXECUTE Stop_Shift_Focus_To_Verbs_Or_Actions

    ELSE
        IF Every_Implementing_Class_Uses_All_Methods IS True THEN
            EXECUTE Leave_It_Alone_ISP_Compliant
        ELSE
            EXECUTE Split_Interface_Into_Smaller_Pieces
        END IF

    END IF

END ISP_Design_Check

The "Role vs. Header" Rule: Do not bundle administrative methods with operational methods. For instance, do not put a deleteAccount() method into the same interface that handles basic public user profile viewing.
The "-able" Naming Trick: When creating interfaces, try naming them with adjectives ending in "-able" or "-or" (e.g., Loggable, Renderable, Exportable, SmsSender). This naturally forces you to focus on a single, specific behavior rather than a massive corporate role.
Refactor with Interface Inheritance: If you legitimately need a large interface for a complex class, you can still respect ISP by composing it out of smaller interfaces using inheritance:

interface SimpleReader { public function read(); }
interface SimpleWriter { public function write(); }

// Advanced classes can implement this, while simple classes can just use Reader or Writer
interface AdvancedStorage extends SimpleReader, SimpleWriter { 
    public function clearCache(); 
}

Summary for Decision Making

Interfaces should be designed from the perspective of the client class that calls them, not the concrete class that implements them. If a client only needs to read data, give it an interface that only allows reading.

The Laravel Blueprint: Mastering ISP

Let's look at a common mistake when building a standard E-commerce checkout or inventory system in Laravel, and how to solve it like a framework architect.

❌ The Junior Approach (Violates ISP)

A junior developer creates a single, monolithic interface to handle all types of products in the store's inventory. [7]

namespace App\Contracts;

interface ProductContract
{
    public function getPrice(): int;
    public function getWeight(): float;
    public function getShippingDimensions(): array;
}

This interface works perfectly for a physical product like a Laptop. But look what happens when the developer tries to implement it for a Digital E-Book or a Software License:

namespace App\Services;

use App\Contracts\ProductContract;

class EBookProduct implements ProductContract
{
    public function getPrice(): int {
        return 999; // ₹999
    }

    // ❌ ISP VIOLATION! E-books do not have physical weight.
    public function getWeight(): float {
        return 0.0; // Useless filler value to satisfy PHP compiler
    }

    // ❌ ISP VIOLATION! E-books do not ship in boxes.
    public function getShippingDimensions(): array {
        throw new \Exception("Digital products do not have shipping dimensions!");
    }
}

The Problem: Your OrderShippingService iterates over all cart items. If it accidentally calls getShippingDimensions() on an EBookProduct, your entire checkout crashes. The interface forced a digital class to inherit physical real-world problems.

The Laravel Mastery Approach (Adheres to ISP)

To build this like the creators of Laravel, we split the behaviors into small, highly specialized contracts.

Step 1: Segregate the Contracts [8]

namespace App\Contracts;

interface Sellable 
{
    public function getPrice(): int;
}

interface Shippable
{
    public function getWeight(): float;
    public function getShippingDimensions(): array;
}

Step 2: Implement only what is required

Now, our classes cleanly bind themselves to exactly what they are capable of doing.

namespace App\Models;

use App\Contracts\Sellable;
use App\Contracts\Shippable;
use Illuminate\Database\Eloquent\Model;

// Physical products implement both contracts
class Laptop extends Model implements Sellable, Shippable
{
    public function getPrice(): int { return 6500000; }
    public function getWeight(): float { return 2.1; }
    public function getShippingDimensions(): array { return; }
}

// Digital products ONLY implement Sellable
class EBook extends Model implements Sellable
{
    public function getPrice(): int { return 999; }
    // No useless weight or dimension code written here!
}

Step 3: Type-Hint accurately in your Services

Your delivery and shipping managers inside Laravel now type-hint the specific behavioral contract, completely isolating them from digital items.

namespace App\Services;

use App\Contracts\Shippable;

class LogisticsService
{
    // This method strictly accepts items that CAN actually be shipped
    public function calculateShippingCost(Shippable $product)
    {
        $weight = $product->getWeight();
        $dimensions = $product->getShippingDimensions();

        // Calculate carrier rates safely...
    }
}

Laravel's Native Mastery Example: Responsable

Laravel natively uses this exact concept with its Illuminate\Contracts\Support\Responsable interface.
Instead of forcing every controller action or custom object to implement a massive layout matrix, Laravel says: "If your class implements Responsable, it must contain exactly one method: toResponse($request)." When a controller returns that object, Laravel checks if it implements that specific interface and executes it automatically.

Summary for Laravel Developers

When creating custom classes, plugins, or traits in Laravel, ask yourself: "Is any class implementing this contract forced to write dummy return values or throw 'Not Supported' exceptions?"
If the answer is yes, break that contract up into smaller pieces immediately.

Liskov Substitution Principle (LSP)

Anas Hussain — Sat, 04 Jul 2026 04:04:34 +0000

The Liskov substitution principle (LSP) states: Objects of a superclass should be replaceable with objects of its subclasses without breaking the application.

In simple terms: A child class must behave exactly like its parent class, so it doesn't surprise the system. If your code expects a generic parent type, you should be able to pass any child variant into it without causing errors, crashes, or weird behaviors.

Keep in mind: Model your classes based on behaviours not on properties. Model your data based on properties and not on behaviours.

The Real-World Example: Think of a TV remote control that runs on standard AA batteries

The Expectation (Parent): The remote expects a standard AA battery. It assumes the battery will fit the slot, provide 1.5 volts of power, and have a positive and negative terminal.
Good Substitution (LSP Compliant): You run out of Duracell batteries, so you buy a Energizer battery or a cheap store-brand battery. They look a bit different, but they provide exactly 1.5V and fit the slot. The remote still works perfectly.
Bad Substitution (LSP Violation): Imagine a company creates a "Smart AA Battery" that is the exact same physical size, but instead of outputting 1.5V continuously, it requires a smartphone app connection to turn on, or it outputs 12V. If you put it in the remote, it either won't power up or it will fry the remote's circuits.

Even though it is technically an "AA Battery" by shape, it violates the expected behavior of an AA battery.

❌ The Wrong Way: Subclasses that break promises (Violates LSP)

A famous technical example is the Square and Rectangle dilemma. A square is technically a rectangle in geometry, but trying to force it into inheritance breaks code logic.

class Rectangle {
    protected $width;
    protected $height;

    public function setWidth($width) { $this->width = $width; }
    public function setHeight($height) { $this->height = $height; }
    public function getArea() { return $this->width * $this->height; }
}

// Square forces both sides to be equal, changing the fundamental rules
class Square extends Rectangle {
    public function setWidth($width) {
        $this->width = $width;
        $this->height = $width; // Modifies height unexpectedly!
    }
    public function setHeight($height) {
        $this->width = $height; // Modifies width unexpectedly!
        $this->height = $height;
    }
}

Why this breaks the system:
If a developer writes a function expecting a standard Rectangle, they assume changing the width won't touch the height.

function render(Rectangle $rectangle) {
    $rectangle->setWidth(10);
    $rectangle->setHeight(5);

    // If you pass a Rectangle: 10 * 5 = 50 (Correct)
    // If you pass a Square: 5 * 5 = 25 (❌ Broken! The width got silently overwritten)
    echo $rectangle->getArea(); 
}

✅The Right Way: Proper Abstraction (Adheres to LSP)

To fix this, child classes should never change the rules of the parent. If they behave differently, they shouldn't share the same direct inheritance line for those specific properties.

interface Shape {
    public function getArea(): float;
}

class Rectangle implements Shape {
    public function __construct(protected float $width, protected float $height) {}
    public function getArea(): float { return $this->width * $this->height; }
}

class Square implements Shape {
    public function __construct(protected float $side) {}
    public function getArea(): float { return $this->side * $this->side; }
}

Now, you can substitute Rectangle or Square anywhere a Shape is expected, and the getArea() method will always return the correct result without any unexpected side effects.

Why this helps you

Polymorphism: Enables the use of polymorphic behavior, making code more flexible and reusable.
Reliability: Ensures that subclasses adhere to the contract defined by the superclass.
Predictability: Guarantees that replacing a superclass object with a subclass object won't break the program.

The Golden Rules to avoid breaking LSP

Don't throw unexpected exceptions: If the parent method doesn't throw errors, your child method shouldn't throw a MethodNotImplementedException.
Don't weaken preconditions: A child class cannot demand more strict inputs than the parent class.
Don't strengthen postconditions: A child class must return the same type of output data expected by the parent.

The 3 Main Confusions Cleared Up

1. Confusion: "If Class B passes the instanceof check for Class A, isn't it LSP compliant?"

Reality: No. Your PHP compiler only checks syntax, not behavior. If your parent class returns an array, and your child class returns null or throws a NotImplementedException, it passes PHP's syntax checks but completely destroys LSP at runtime.

2. Confusion: "Does LSP mean child classes cannot add new methods?"

Reality: Child classes can add as many new methods as they want. LSP only cares about the inherited methods. The child must not break the existing promises made by the parent methods.

3. Confusion: "Real-world relationships map directly to code inheritance, right?"

Reality: This is the biggest trap in programming. In the real world, an Ostrich is a Bird. But in code, if your Bird class has a fly() method, making Ostrich extends Bird will force you to break LSP because ostriches cannot fly. Code relationships are based on what objects can DO, not what they ARE.

The Ultimate LSP Cheat Sheet (The 3 Violations)

You are violating LSP if your child class does any of these three things:

The Violation	What it looks like in PHP	Why it breaks the app
1. The Slacker	Throws a NotImplementedException or returns false for an inherited method.	Code expecting the parent class will crash unexpectedly.
2. The Secret Agent	Requires a completely different, stricter type of input than the parent.	Code passing valid inputs to the parent will fail on the child.
3. The Traitor	Changes or strips out the data type that the parent promised to return.	Code trying to read the result will trigger an error.

The 3-Step Decision Matrix (How to Choose)

When writing a subclass or implementing an interface in PHP, use this mental map to ensure LSP compliance:

START LSP_Design_Check

    IF Child_Disables_Or_Throws_Error_For_Inherited_Method IS True THEN
        EXECUTE Stop_Do_Not_Use_Inheritance_Use_Composition_Instead

    ELSE
        IF Child_Changes_Expected_Type_Of_Inputs_Or_Outputs IS True THEN
            EXECUTE Fix_Your_Types_To_Match_The_Parent_Exactly
        ELSE
            EXECUTE Leave_It_Alone_LSP_Compliant
        END IF

    END IF

END LSP_Design_Check

The "Throw-Away" Test: Am I about to write a method in my child class that just says throw new Exception("Not supported")? If yes, do not extend that parent.
The "If Instanceof" Smell: Look at your controller code. Do you ever see blocks like this?

if ($payment instanceof CryptoPayment) {
    $payment->connectWallet(); // ❌ LSP Smell!
}
$payment->process();

If you have to explicitly check which child class you are holding to execute unique logic, your abstraction is broken. Move that unique logic inside the process() method itself.

Composition Over Inheritance: If you want Class B to reuse code from Class A, but Class B doesn't share the exact same behaviors, do not use extends. Instead, pass Class A into Class B's constructor (Composition) or use a PHP trait.

Summary for Decision Making

If your code handles a parent class, it should never care, know, or suspect if it is actually holding a child class. The swap should be completely invisible.

The Laravel Blueprint: Mastering LSP

Let's look at how a Junior developer violates LSP in Laravel versus how a Master architectures it using Laravel's Cache system.

❌ The Junior Approach (Violates LSP)

Imagine your app uses Redis for fast caching, but for local development, you use simple File caching. A junior developer creates a custom wrapper but changes the behavioral rules of the output.

namespace App\Services;

use Illuminate\Support\Facades\Cache;

class CustomCacheService
{
    public function getUserData(string $key)
    {
        $data = Cache::get($key);

        // ❌ LSP VIOLATION SMELL!
        // Redis returns an Object, but File cache returns a raw String.
        // The developer has to write conditional logic depending on the driver!
        if (config('cache.default') === 'redis') {
            return json_decode($data);
        }

        return $data; 
    }
}

Why this breaks Laravel Mastery: The application code now cares about which driver is running behind the scenes. If you switch drivers in your .env file, your code logic breaks.

The Laravel Mastery Approach (Adheres to OCP & LSP)

Laravel provides the Illuminate\Contracts\Cache\Repository contract. Any cache driver Laravel uses (Redis, Memcached, Database, File) must strictly adhere to the behavior defined by this contract.
No matter which driver is swapped in via the Service Container, it must return exactly what is expected without requiring if/else checks in your Controller.

Step 1: Trusting the Contract in your Controller

Your controller type-hints the Laravel Contract. It does not care if the data is coming from a hard drive or an in-memory Redis cluster.

namespace App\Http\Controllers;

use Illuminate\Contracts\Cache\Repository as CacheContract;
use App\Models\User;

class UserController extends Controller
{
    // Laravel automatically injects whatever driver is active in config/cache.php
    public function __construct(
        protected CacheContract $cache
    ) {}

    public function show($id)
    {
        // LSP Guarantee: Every single Laravel cache driver MUST return 
        // the item if found, or NULL if it doesn't exist. 
        // No driver is allowed to throw a "FileNotFoundException".
        $user = $this->cache->remember("user:{$id}", 3600, function () use ($id) {
            return User::findOrFail($id);
        });

        return response()->json($user);
    }
}

Step 2: Creating a Custom Driver Safely (Abiding by LSP)

If your company builds a custom internal caching system (e.g., Couchbase) and you want to integrate it into Laravel, your custom driver must follow the rules of the parent Repository contract.

namespace App\Extensions;

use Illuminate\Contracts\Cache\Repository;

class CouchbaseCacheDriver implements Repository
{
    // You MUST implement all methods, and they MUST behave identical to Redis/File
    public function get($key, $default = null)
    {
        $value = $this->couchbase->find($key);

        // LSP Rule: If missing, return the default value (null), 
        // do not throw an error or return false!
        return $value ?? $default; 
    }

    // ... implement other required contract methods
}

Summary for Laravel Developers

When writing extensions, packages, or custom drivers in Laravel, ask yourself: "If I swap this implementation in my .env or Service Provider, will I have to change a single line of code inside my Controllers or Jobs?"
If the answer is yes, your child class has broken the behavioral promises of the parent contract, violating LSP.

Open Closed Principle (OCP)

Anas Hussain — Thu, 02 Jul 2026 08:16:07 +0000

The open-closed principle (OCP) states that software entities should be open for extension, but closed for modification; that is, such an entity can allow its behaviour to be extended without modifying its source code.

In simple terms: You should be able to add new features to your code without changing or breaking the existing code.

Importance:

Extensibility: New features can be added without modifying existing code.
Stability: Reduces the risk of introducing bugs when making changes.

- Flexibility: Adapts to changing requirements more easily.

The Real-World Example: Think of the electrical wall outlet in your home.

Closed for Modification: The outlet is wired permanently behind your drywall. You do not tear down the wall, change the house wiring, or rebuild the electrical grid every time you buy a new device.
Open for Extension: The outlet provides a standard interface (the plug holes). You can plug in a phone charger, a vacuum cleaner, a toaster, or a television.

The outlet does not need to know what appliance you are plugging into it ahead of time. It is open to powering any device, as long as that device fits the standard plug shape.

Imagine you run an online store, and you need to calculate shipping costs for different shipping methods.

❌ The Wrong Way: Modifying the existing class (Violates OCP)

Every time your company decides to offer a new shipping carrier (like DHL or FedEx), you have to open this existing file and add another if/else block.

class ShippingCostCalculator {
    public function calculate($weight, $carrier) {
        if ($carrier === 'FedEx') {
            return $weight * 1.5;
        } elseif ($carrier === 'UPS') {
            return $weight * 1.2;
        }
        // ❌ If you want to add DHL tomorrow, you must modify this file.
        // If you make a typo, you break FedEx and UPS shipping for everyone.
    }
}

✅The Right Way: Extending without modifying (Adheres to OCP)

Instead of one giant class making all the decisions, we create a standard contract (Interface). The main calculator stays closed to modification, but the system is open to extension by simply adding new files.

Step 1: Create the standard "Outlet" (Interface)

interface ShippingRate {
    public function getRate(float $weight): float;
}

Step 2: Create the "Appliances" (Plugging in new features)

To add a new carrier, you just create a completely separate, isolated class file.

class FedExShipping implements ShippingRate {
    public function getRate(float $weight): float {
        return $weight * 1.5;
    }
}

class UpsShipping implements ShippingRate {
    public function getRate(float $weight): float {
        return $weight * 1.2;
    }
}

// Want to add DHL? Just create a new file! No need to touch FedEx or UPS.
class DhlShipping implements ShippingRate {
    public function getRate(float $weight): float {
        return $weight * 2.0;
    }
}

Step 3: Run the system safely

The core logic never changes, no matter how many carriers you add to your company.

class ShippingCostCalculator {
    // This method is CLOSED to modification. It doesn't care about specific brands.
    public function calculate(float $weight, ShippingRate $shippingMethod) {
        return $shippingMethod->getRate($weight);
    }
}

Why this helps you

Extensibility: New features can be added without modifying existing code.
Stability: Reduces the risk of introducing bugs when making changes.
Flexibility: Adapts to changing requirements more easily.
Team Collaboration: Ten different developers can work on ten different shipping methods at the same time without editing the same file and causing code conflicts.

The 3 Main Confusions Cleared Up

1. Confusion: "Closed for modification means I can never touch this file again?"

Reality: No. "Closed" means closed for behavioral changes to existing features, or changes driven by new requirements. If you find a bug in the class, you absolutely must open and modify the file to fix it.

2. Confusion: "Should I create an Interface for every single class?"

Reality: This is the #1 mistake that kills performance and readability. If a class has exactly one implementation that will never change (e.g., a PdfGenerator that only generates PDFs), do not create an interface. Only use interfaces where variance is expected.

3. Confusion: "Does OCP mean I must predict the future?"

Reality: You cannot guess every feature your client will ask for in two years. OCP does not mean predicting the future; it means structuring code so that when the future happens, it is easy to plug in.

The Anti-Pattern vs. The OCP Solution

❌ The 90% Approach: Modifying the existing class (Violates OCP)

Every time a manager asks for a new payment gateway, the engineer opens this class and adds another elseif. One typo can crash the entire checkout system.

class PaymentProcessor {
    public function process($amount, $type) {
        if ($type === 'paypal') {
            // PayPal logic
        } elseif ($type === 'stripe') {
            // Stripe logic
        } elseif ($type === 'crypto') { // ❌ Had to modify this file to add this!
            // Crypto logic
        }
    }
}

The 10% Approach: Using Polymorphism (Adheres to OCP)

We create a contract (Interface). The main processor never changes, no matter how many gateways you add.

interface PaymentGateway {
    public function pay($amount);
}

// The core logic is now CLOSED to modification
class PaymentProcessor {
    public function process($amount, PaymentGateway $gateway) {
        $gateway->pay($amount); // Dynamic execution
    }
}

// OPEN to extension: Just add a new class file!
class StripeGateway implements PaymentGateway {
    public function pay($amount) { /* Stripe logic */ }
}
class CryptoGateway implements PaymentGateway {
    public function pay($amount) { /* Crypto logic */ }
}

The 3-Step Decision Matrix (How to Choose)

When writing or reviewing a PHP class, use this mental map to decide if you need to apply OCP:

  START OCP_Design_Check

    IF Is_Writing_Conditional_Statement IS True THEN

        IF Conditions_Likely_To_Grow_In_Future IS True THEN
            EXECUTE Apply_OCP_Use_An_Interface
        ELSE
            EXECUTE Simple_If_Else_Is_Fine
        END IF

    ELSE
        EXECUTE Leave_It_Alone
    END IF

END OCP_Design_Check

Is it a variation of a type? If you are writing conditions based on "types" (e.g., user_type, payment_method, report_format, export_destination), it is a prime candidate for OCP. Turn those types into separate classes implementing an interface.
Is it a simple binary state? If you are checking if ($user->isActive), leave it alone. Do not create an ActiveUser and InactiveUser class. That is over-engineering.
The "Three Strikes" Rule: If you don't know if a feature will expand, don't guess. Write the simple if/else first. The second time you modify it, let it go. The third time you have to open that file to add another condition, refactor it to OCP immediately.

Summary for Decision Making

Modify code only to fix bugs or optimize existing logic.
Extend code (by adding new files/classes) to add completely new business rules or features.

The Laravel Blueprint: Mastering OCP

In Laravel, the "wall outlet" is an Interface (often called a Contract), and the "appliances" are your classes. Imagine your Laravel app needs to send marketing alerts to users. Initially, your boss asks for SMS alerts via Twilio.

❌ The Junior Approach (Violates OCP)

A junior developer hardcodes Twilio directly into the service.

namespace App\Services;

use Twilio\Rest\Client;

class OrderNotificationService 
{
    public function sendAlert($user, $message) 
    {
        // Hardcoded dependency on Twilio
        $twilio = new Client(config('twilio.sid'), config('twilio.token'));
        $twilio->messages->create($user->phone, ['body' => $message]);
    }
}

The Problem: Two months later, the boss says, "Twilio is too expensive, let's switch to Vonage for SMS, and also add WhatsApp alerts!" You now have to open this class, delete code, and rewrite it. This risks breaking your existing deployment.

The Laravel Mastery Approach (Adheres to OCP)

To write this like a Laravel senior architect, you use a Contract and Laravel's Service Container.

Step 1: Create the "Outlet" (The Contract)

namespace App\Contracts;

interface SmsSender 
{
    public function send(string $to, string $message): bool;
}

Step 2: Create the "Appliances" (The Providers)

Now, create separate classes for each service. If you need to add a new one later, you just create a new file.

namespace App\Services;

use App\Contracts\SmsSender;

class TwilioSender implements SmsSender 
{
    public function send(string $to, string $message): bool {
        // Twilio specific API code here
        return true;
    }
}

class VonageSender implements SmsSender 
{
    public function send(string $to, string $message): bool {
        // Vonage specific API code here
        return true;
    }
}

Step 3: Inject the Contract into your Service

Your service is now closed for modification. It only knows about the interface, not the concrete brands.

namespace App\Services;

use App\Contracts\SmsSender;

class OrderNotificationService 
{
    // Laravel automatically injects the correct sender here!
    public function __construct(
        protected SmsSender $smsSender
    ) {}

    public function sendAlert($user, $message) 
    {
        $this->smsSender->send($user->phone, $message);
    }
}

Step 4: The Magic Switch (AppServiceProvider)

How does Laravel know which appliance is plugged into the outlet? You tell it in your AppServiceProvider.php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use App\Contracts\SmsSender;
use App\Services\TwilioSender;
use App\Services\VonageSender;

class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // To switch from Twilio to Vonage globally, change exactly ONE line here:
        $this->app->bind(SmsSender::class, TwilioSender::class);
    }
}

Why this makes you a Laravel Master

Zero-Risk Feature Additions: When the boss wants to add WhatsApp tomorrow, you don't touch OrderNotificationService. You just write a WhatsAppSender file and swap it in the Service Provider.
Mocking & Testing: In your feature tests, you can swap the implementation with a fake one (SmsSender::fake()) so you don't accidentally send real text messages during testing.

Single Responsibility Principle (SRP)

Anas Hussain — Tue, 30 Jun 2026 04:32:00 +0000

The single-responsibility principle (SRP) states that there should never be more than one reason for a class to change. In other words, every class should have only one responsibility. A module should be responsible to one, and only one, actor. The term actor refers to a group (consisting of one or more stakeholders or users) that requires a change in the module.

In simple terms: Do one thing, and do it well.

The Real-World Example: Imagine you are hiring a chef for a restaurant.

Bad Design (The "Do-Everything" Chef): You hire a chef who must cook the food, wash the dishes, calculate the restaurant's taxes, and repair the plumbing when a pipe bursts.
The Problem: If the tax laws change, your chef is busy studying accounting instead of cooking. If they mess up the plumbing, the kitchen floods, and the entire restaurant shuts down. One change ruins everything.
Good Design (SRP applied): You hire a chef to cook, a dishwasher to clean, an accountant for taxes, and a plumber for repairs.
The Benefit: If tax laws change, only the accountant changes their workflow. The chef keeps cooking without interruption.

❌ Wrong Approach: A class with too many jobs

This User class handles user data, database connections, and email delivery. It has three reasons to change.

class User {
    private $name;
    private $email;

    public function __construct($name, $email) {
        $this->name = $name;
        $this->email = $email;
    }

    // Job 1: Manage User Data
    public function getName() { return $this->name; }

    // Job 2: Database Operations (Reason to change: Switching database types)
    public function saveToDatabase() {
        echo "Saving user to database...\n";
    }

    // Job 3: Notification Logic (Reason to change: Switching from Email to SMS)
    public function sendWelcomeEmail() {
        echo "Sending email to " . $this->email . "\n";
    }
}

✅ Right Approach: Splitting responsibilities

We break the big class into three tiny, specialized classes. Each has exactly one job.

// 1. Responsible ONLY for user data representation
class User {
    private $name;
    private $email;

    public function __construct($name, $email) {
        $this->name = $name;
        $this->email = $email;
    }

    public function getName() { return $this->name; }
    public function getEmail() { return $this->email; }
}

// 2. Responsible ONLY for saving data
class UserRepository {
    public function save(User $user) {
        echo "Saving " . $user->getName() . " to the database.\n";
    }
}

// 3. Responsible ONLY for sending messages
class EmailService {
    public function sendWelcome(User $user) {
        echo "Sending email to " . $user->getEmail() . "\n";
    }
}

Why this helps you

Maintainability: When classes have a single, well-defined responsibility, they're easier to understand and modify.
Testability: It's easier to write unit tests for classes with a single focus.
Flexibility: Changes to one responsibility don't affect unrelated parts of the system.
Reusability: You can use the EmailService to send emails for orders, resets, or other features.

The 3 Main Confusions Cleared Up for the SRP implementation

1. Confusion: "Does 'one responsibility' mean a class can only have one method?"

Reality: No. A responsibility is a cohesive business role, not a single action.
Example: A UserRepository class can have save(), delete(), findById(), and update(). This is still one responsibility: managing user data storage.

2. Confusion: "What exactly defines a 'reason to change'?"

Reality: Robert C. Martin (the creator of SOLID) clarified that a "reason to change" refers to people, not technology. A responsibility is defined by who requests the change (the actors).
Example: If the Accounting department asks for a change, and the HR department asks for a change, those are two different actors. They should never share the same PHP class.

3. Confusion: "When do I stop splitting classes?"

Reality: Engineers often split code prematurely, creating UserEmailValidator, UserPasswordValidator, and UserAgeValidator before they even need them. This causes "analysis paralysis."

The 3-Step Decision Matrix (How to Choose)

When looking at a PHP class, ask yourself these three strict questions to decide if you need to split it:

Is this class serving more than one business department/actor?

START SRP_Decision_Process

    IF Class_Serves_Multiple_Departments_Or_Actors IS True THEN
        EXECUTE Split_Class_Immediately

    ELSE
        IF Class_Mixes_Different_Technical_Layers IS True THEN
            EXECUTE Split_Class
        ELSE
            EXECUTE Leave_It_Alone
        END IF

    END IF

END SRP_Decision_Process

Who is asking for this feature? If a bug fix for the marketing team's email layout can accidentally break the accounting team's invoice calculation, your class has too many responsibilities.
Are different technical layers mixed? If a single PHP class contains raw SQL queries (SELECT *), HTML markup (<div>), and validation logic (if (empty)), it violates SRP. Split them.
Can I describe the class without using the word "AND"?
- Bad: "This class holds user data and saves it to MySQL and sends a Slack alert." (3 responsibilities)
- Good: "This class sends Slack alerts." (1 responsibility)

Real-World Decision Rule: "Don't Split Until It Hurts"

To avoid over-engineering, follow the Tactical SRP Rule:

Start by writing your code in a single class if the feature is small.
The moment you need to reuse a piece of it (like using the email logic somewhere else), extract it into its own class.
The moment a class grows past 200 lines of code, audit it using the decision matrix above.

The Laravel Blueprint: Mastering SRP

Let's look at a classic Laravel mistake: putting user registration logic, database insertion, profile photo manipulation, and welcome notifications all inside a single Controller method.

❌ The Junior Approach: The "Do-Everything" Controller (Violates SRP)

This controller method has four distinct reasons to change: database changes, validation rules, image optimization tweaks, and notification carrier changes.

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\Http\Request;
use Intervention\Image\Facades\Image;
use Illuminate\Support\Facades\Mail;

class RegisterController extends Controller
{
    public function store(Request $request)
    {
        // Reason to change 1: Validation rules change
        $request->validate([
            'name' => 'required',
            'email' => 'required|email|unique:users',
            'avatar' => 'required|image'
        ]);

        // Reason to change 2: Handling image manipulation
        $avatar = $request->file('avatar');
        $filename = time() . '.' . $avatar->getClientOriginalExtension();
        Image::make($avatar)->resize(300, 300)->save(public_path('/uploads/' . $filename));

        // Reason to change 3: Database architecture updates
        $user = User::create([
            'name' => $request->name,
            'email' => $request->email,
            'avatar' => $filename,
        ]);

        // Reason to change 4: Switching from Email to Slack/SMS
        Mail::to($user->email)->send(new \App\Mail\WelcomeMail($user));

        return response()->json(['message' => 'User created successfully!'], 201);
    }
}

The Laravel Mastery Approach (Adheres to SRP)

To build this like a framework architect, we segregate the tasks using dedicated Laravel features: Form Requests, Service Classes, and Events/Listeners.

Step 1: Handle Validation via Form Request

The controller doesn't need to know the validation rules. We delegate this to a dedicated request file.

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class RegisterRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'name' => 'required|string|max:255',
            'email' => 'required|email|unique:users,email',
            'avatar' => 'required|image|max:2048'
        ];
    }
}

Step 2: Extract Core Logic into a Action/Service Class

We create a dedicated PHP class whose only job is to orchestrate user registration and file handling.

namespace App\Actions;

use App\Models\User;
use App\Events\UserRegistered;
use Illuminate\Http\UploadedFile;

class RegisterNewUser
{
    public function execute(array $data, UploadedFile $avatar): User
    {
        // Handle the file upload logic cleanly
        $path = $avatar->store('avatars', 'public');

        $user = User::create([
            'name' => $data['name'],
            'email' => $data['email'],
            'avatar' => $path,
        ]);

        // Fire an event! This class doesn't care HOW notifications are sent.
        event(new UserRegistered($user));

        return $user;
    }
}

Step 3: Handle Communications via Events & Listeners

When the user is saved, an event fires. A dedicated Listener catches it and sends the mail asynchronously.

namespace App\Listeners;

use App\Events\UserRegistered;
use App\Mail\WelcomeMail;
use Illuminate\Support\Facades\Mail;
use Illuminate\Contracts\Queue\ShouldQueue;

class SendWelcomeNotification implements ShouldQueue
{
    public function handle(UserRegistered $event): void
    {
        // This class only changes if the notification delivery method changes
        Mail::to($event->user->email)->send(new WelcomeMail($event->user));
    }
}

Step 4: The Clean, Slim Master Controller

Now look at the controller. It has exactly one responsibility: Receive the HTTP request and return an HTTP response. It is highly readable and closed to external bugs.

namespace App\Http\Controllers;

use App\Http\Requests\RegisterRequest;
use App\Actions\RegisterNewUser;

class RegisterController extends Controller
{
    public function store(RegisterRequest $request, RegisterNewUser $registerAction)
    {
        // Execution is offloaded to specialized workers
        $user = $registerAction->execute(
            $request->validated(),
            $request->file('avatar')
        );

        return response()->json(['user' => $user], 201);
    }
}

Why this makes you a Laravel Master

Testing Simplicity: You can write a unit test for RegisterNewUser by passing a fake uploaded file without ever rendering an HTTP router or acting like a web browser.
Impeccable Reusability: If you need to register a user via an API Endpoint, a Blade Web Form, or a Terminal Artisan Command, you simply inject the RegisterNewUser action class and run it. You never have to duplicate code.

NumPy on Ubuntu: From Zero to First Arrays

Anas Hussain — Wed, 27 Aug 2025 03:35:11 +0000

Why this post?

Today I set up a clean Python workspace on Ubuntu and ran my first NumPy code. I wrote down every step so you (or future‑me) can repeat it in minutes.

Prerequisites
Install Python and pip
Create a Virtual Environment
Install NumPy and Jupyter
Launch Jupyter Notebook
Your First NumPy Operations
Shut Down & Deactivate
Common Pitfalls & Fixes
What’s Next

Prerequisites

Ubuntu (works on 20.04/22.04/24.04+)
Terminal access
Basic comfort running shell commands

Tip: Commands with $ go in your terminal. Don’t copy the $ itself.

Install Python and pip

Ubuntu ships with Python 3, but let’s make sure the essentials are installed and up‑to‑date.

$ sudo apt update && sudo apt install -y python3 python3-pip python3-venv
$ python3 --version
$ pip3 --version

Create a Virtual Environment

Make a dedicated folder for your NumPy learning so packages don’t leak into system Python.

$ mkdir -p ~/numpy-learning && cd ~/numpy-learning
$ python3 -m venv numpy-venv
$ source numpy-venv/bin/activate
(numpy-venv) $ which python

You should see something like /home/you/numpy-learning/numpy-venv/bin/python. The (numpy-venv) prefix means the environment is active.

Why venv? Each project gets its own clean set of packages. No conflicts.

Install NumPy and Jupyter

First, bring pip up to date, then install the tools we need:

(numpy-venv) $ python -m pip install --upgrade pip
(numpy-venv) $ pip install numpy jupyter

Optional but handy for data work:

(numpy-venv) $ pip install matplotlib pandas

Verify installs:

(numpy-venv) $ python -c "import numpy as np; print(np.__version__)"
(numpy-venv) $ jupyter --version

Launch Jupyter Notebook

Start the notebook server. Your browser will open automatically (or you’ll get a URL with a token to paste into your browser):

(numpy-venv) $ jupyter notebook

In the Jupyter UI:

Click New → Python 3 (ipykernel).
Rename it to numpy_basics.ipynb (click the title at the top).

Take a look into my Jupyter UI

Your First NumPy Operations

Create a few cells and run the following. (Click a cell and press Shift+Enter to run.)

Cell 1 — Import & version

import numpy as np
print("NumPy version:", np.__version__)

Cell 2 — Create arrays

# 1D and 2D arrays
a = np.array([1, 2, 3, 4, 5])
b = np.array([[1, 2, 3],
              [4, 5, 6]])
print("a:", a)
print("b:\n", b)

Cell 3 — Properties

print("a.shape:", a.shape, "a.dtype:", a.dtype)
print("b.shape:", b.shape, "b.ndim:", b.ndim, "b.size:", b.size)

Cell 4 — Indexing & slicing

print("First of a:", a[0])
print("Last two of a:", a[-2:])
print("b second column:", b[:, 1])

Cell 5 — Vectorized operations

print("a * 2:", a * 2)
print("a + 10:", a + 10)
print("a ** 2:", a ** 2)

Cell 6 — Broadcasting

row = np.array([10, 20, 30])
print("b + row:\n", b + row)

Cell 7 — Aggregations

arr = np.array([10, 20, 30, 40, 50])
print("sum:", np.sum(arr))
print("mean:", np.mean(arr))
print("std:", np.std(arr))
print("min:", np.min(arr), "max:", np.max(arr))

Cell 8 — Reshape

reshaped = b.reshape(3, 2)
print("reshaped b (3x2):\n", reshaped)

That’s it — your first NumPy session is done!

Shut Down & Deactivate

When you’re finished for the day:

In the Jupyter tab: File → Save and Checkpoint.
In the terminal where Jupyter is running: press Ctrl + C and confirm to stop the server.
Deactivate your virtual environment:

(numpy-venv) $ deactivate

Next time, come back with:

$ cd ~/numpy-learning
$ source numpy-venv/bin/activate
(numpy-venv) $ jupyter notebook

Common Pitfalls & Fixes

❌ pip installs to the wrong place

Always use python -m pip ... inside your venv to be explicit.

(numpy-venv) $ python -m pip install numpy jupyter

❌ jupyter: command not found after install

Make sure your venv is active (look for (numpy-venv)), then reinstall:

$ source numpy-venv/bin/activate
(numpy-venv) $ python -m pip install --upgrade pip jupyter

❌ Mixing system Python and venv Python

Check which Python is running:

(numpy-venv) $ which python

It should point to your project’s numpy-venv folder.

❌ Permission errors

Avoid sudo pip. Use a venv. If needed, upgrade pip:

(numpy-venv) $ python -m pip install --upgrade pip

What’s Next

Try JupyterLab for a modern UI:

  (numpy-venv) $ pip install jupyterlab
  (numpy-venv) $ jupyter lab

Explore: np.arange, np.linspace, np.random.rand, np.vstack, np.hstack.
Add matplotlib and plot your arrays.
Day 2 topics: boolean masking, fancy indexing, broadcasting tricks, and small exercises.

If this helped, drop a comment or share what you built with NumPy today! 💡🚀

Text to speech

Anas Hussain — Fri, 21 Feb 2025 09:22:50 +0000

📌 [Title of the Blog Post]

✅ Prerequisites

Before starting this tutorial, make sure you have the following:

🔍 Basic understanding of python.
🛠️ Installed python3 and .
💻 A working development environment ([e.g., XAMPP, MAMP, or Docker]).

🎯 Intention of This Tutorial

In this tutorial, you will learn:

📖 [Main objective of the tutorial, e.g., how to build a REST API using Laravel.]
🚀 [Specific features or tools you'll implement, e.g., Symfony DOM Crawler integration.]
🛠️ [Real-world application or practical use case, e.g., building a simple e-commerce product filter.]

This guide is aimed at [Beginner/Intermediate/Advanced] developers who want to [main goal, e.g., improve backend development skills].

⚠️ Faced Challenges

During this project, I encountered the following challenges:

❌ [Describe a specific challenge, e.g., configuring the database connection in Laravel.]
🐛 [Mention any bugs or errors faced, e.g., handling unexpected errors with PHPUnit.]
🔄 [Technical roadblocks, e.g., integrating third-party APIs or managing dependencies.]

💡 What I Learned New

This tutorial taught me some valuable lessons:

📌 [New concepts learned, e.g., advanced error handling in PHP.]
🛠️ [New tools or libraries explored, e.g., Symfony components.]
💻 [Best practices discovered, e.g., database optimization techniques in Laravel.]

💻 Development Setup

🔧 Step 1: Install Required Tools


bash
# Example commands for setup
sudo apt update
sudo apt install php8.2 composer mysql-server

Laravel Application Setup with Docker: A Step-by-Step Guide

Anas Hussain — Tue, 14 Jan 2025 22:02:25 +0000

Prerequisites

A system with Docker support (Linux, macOS, or Windows).
Basic knowledge of Laravel and Docker.

Step 1: Install Docker

For Linux

Update your system packages:

   sudo apt-get update

Install Docker:

   sudo apt-get install -y docker.io

Start and enable Docker:

   sudo systemctl start docker  
   sudo systemctl enable docker

For macOS and Windows

Download and install Docker Desktop from Docker's official site.

Step 2: Set Up the Laravel Project

Clone the Project Repository

git clone <your-repo-url>  
cd <project-name>

Install Dependencies

composer install

Prepare the Environment

Create a .env file:

   cp .env.example .env

Generate the application key:

   php artisan key:generate

Update the `Dockerfile` and `docker-compose.yml`

Example `Dockerfile`

FROM php:8.2-apache  
WORKDIR /var/www/html  
COPY . .  
RUN docker-php-ext-install pdo pdo_mysql

Example `docker-compose.yml`

version: '3.8'  
services:  
  app:  
    build: .  
    ports:  
      - "8080:80"  
    volumes:  
      - .:/var/www/html  
    environment:  
      - APACHE_LOG_DIR=/var/log/apache2  
    depends_on:  
      - db  

  db:  
    image: mysql:8.0  
    environment:  
      MYSQL_ROOT_PASSWORD: root  
      MYSQL_DATABASE: laravel  
      MYSQL_USER: laravel  
      MYSQL_PASSWORD: secret

Build and Start Docker Containers

docker-compose build  
docker-compose up -d

Set Permissions

chmod -R 775 bootstrap/cache storage  
chown -R www-data:www-data bootstrap/cache storage  
chmod 775 database  
chown -R www-data:www-data database  
chmod 664 database/database.sqlite  
chown www-data:www-data database/database.sqlite

Migrate the Database

php artisan migrate

Step 3: Access the Application

Once the containers are running, access your Laravel application at:

http://localhost:8080

Step 4: Reference

Find the complete project code on GitHub:

GitHub Repository Link

Step 5: Most Used Docker Commands

Basic Commands

docker --version: Check Docker version.
docker ps: List running containers.
docker ps -a: List all containers.
docker images: List all Docker images.
docker pull <image>: Pull an image from Docker Hub.
docker build -t <name> .: Build an image from a Dockerfile.
docker run -d -p <host-port>:<container-port> <image>: Run a container.
docker exec -it <container-id> bash: Access a container's shell.
docker stop <container-id>: Stop a running container.
docker rm <container-id>: Remove a stopped container.

Advanced Commands

docker logs <container-id>: View container logs.
docker-compose up: Start services defined in docker-compose.yml.
docker-compose down: Stop and remove services.
docker volume ls: List volumes.
docker network ls: List networks.
docker inspect <container-id>: Inspect container details.
docker system prune: Clean up unused containers, images, and volumes.
docker cp <src> <container>:<dest>: Copy files to a container.
docker stats: View real-time resource usage.
docker tag <image-id> <new-name>: Tag an image.

Refer to the Docker Documentation for more commands and usage examples.

By following these steps, you’ll have a Laravel application running in Docker in no time!

Laravel Authentication Using Passport

Anas Hussain — Thu, 02 Jan 2025 12:01:17 +0000

Mastering Laravel Authentication with Passport: A Step-by-Step Guide

Authentication is a cornerstone of modern web applications. In Laravel, Passport provides a full OAuth2 server implementation, enabling API authentication seamlessly. This guide walks you through the entire process of setting up Laravel Passport, from installation to securing and testing your API.

Introduction

Why Use Laravel Passport?

Laravel Passport simplifies the complexities of OAuth2 authentication by integrating it tightly with Laravel's ecosystem. With Passport, you can:

Authenticate API users securely.
Generate personal access tokens for mobile and web clients.
Manage token expiration and revocation easily.

Prerequisites

Before diving in, ensure you have:

A basic understanding of Laravel.
A Laravel project (v10.x or later is recommended) installed and configured with a database.
PHP 8.0 or later installed.

If you don’t have a project set up, create one with:

composer create-project --prefer-dist laravel/laravel passport-auth
cd passport-auth

Step 1: Install Laravel Passport

Install the Package

Run the following command to add Passport to your project:

composer require laravel/passport

Publish and Migrate Passport Files

Publish the Passport migrations and configuration files:

php artisan vendor:publish --tag=passport-migrations
php artisan migrate

Step 2: Configure Laravel Passport

Install Encryption Keys and Clients

Run the installation command:

php artisan passport:install

This generates encryption keys and creates OAuth clients in your database. Make note of the output, especially the client IDs and secrets.

Optional: Create a Personal Access Client

To create a personal access client explicitly, run:

php artisan passport:client --personal

Step 3: Update the Model

Add the HasApiTokens trait to your user model:

use Laravel\Passport\HasApiTokens;

class User extends Authenticatable
{
    use HasApiTokens, Notifiable;

    // Other properties...
}

Step 4: Update Auth Configuration

Configure Passport as the driver for API guards in config/auth.php:

'guards' => [
    'api' => [
        'driver' => 'passport',
        'provider' => 'users',
    ],
],

Step 5: Register Passport Routes

In App\Providers\AppServiceProvider, load Passport's routes:

use Laravel\Passport\Passport;

public function boot(): void
{
    Passport::routes();
    Passport::tokensExpireIn(now()->addDays(15));
    Passport::refreshTokensExpireIn(now()->addDays(30));
    Passport::personalAccessTokensExpireIn(now()->addMonths(6));
}

Step 6: Build Authentication API Endpoints

Add Routes

Define API routes in routes/api.php:

use App\Http\Controllers\AuthController;

Route::post('/register', [AuthController::class, 'register']);
Route::post('/login', [AuthController::class, 'login']);
Route::middleware('auth:api')->get('/user', [AuthController::class, 'user']);

Create the Authentication Controller

Implement authentication methods:

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use App\Models\User;

class AuthController extends Controller
{
    public function register(Request $request)
    {
        $request->validate([
            'name' => 'required|string|max:255',
            'email' => 'required|string|email|max:255|unique:users',
            'password' => 'required|string|min:8',
        ]);

        $user = User::create([
            'name' => $request->name,
            'email' => $request->email,
            'password' => bcrypt($request->password),
        ]);

        return response()->json([
            'token' => $user->createToken('API Token')->accessToken,
        ], 201);
    }

    public function login(Request $request)
    {
        $credentials = $request->only('email', 'password');

        if (!Auth::attempt($credentials)) {
            return response()->json(['message' => 'Invalid credentials'], 401);
        }

        return response()->json([
            'token' => Auth::user()->createToken('API Token')->accessToken,
        ]);
    }

    public function user()
    {
        return response()->json(Auth::user());
    }
}

Step 7: Set Permissions for Encryption Keys

Ensure secure access to Passport keys:

chmod 600 storage/oauth-private.key storage/oauth-public.key
chown www-data:www-data storage/oauth-private.key storage/oauth-public.key

Verify permissions:

ls -l storage/oauth-*.key

Expected output:

-rw------- 1 www-data www-data 1704 Jan  2 12:00 oauth-private.key
-rw------- 1 www-data www-data  800 Jan  2 12:00 oauth-public.key

Step 8: Test the API

Use Postman or any API client to test endpoints:

Register: Send a POST request to /register with name, email, and password.
Login: Send a POST request to /login with email and password.
Get User Data: Send a GET request to /user with the token in the Authorization header.

Best Practices

Use HTTPS in production.
Rotate encryption keys periodically.
Validate inputs thoroughly.
Limit token scopes for better security.

Conclusion

Congratulations! You've successfully implemented API authentication using Laravel Passport. This setup provides a robust foundation for securing your API. Explore advanced Passport features like scopes, token revocation, and client credentials to further enhance your application's security.

Laravel Zero Downtime Deployments with Envoy

Anas Hussain — Sat, 28 Dec 2024 11:28:26 +0000

Introduction

Introduce the topic by explaining what Laravel Envoy is, its purpose, and why developers should consider using it for deployment automation. Highlight benefits like simplicity, SSH-based execution, and reusable scripts.

Example Introduction:

"Deploying Laravel projects manually can be repetitive and error-prone. With Laravel Envoy, you can automate your deployment process using simple and readable syntax. In this guide, I'll show you how to set up and use Laravel Envoy for seamless deployments."

Advantages of Zero Downtime Deployment

No Downtime: Users always interact with a live application during deployment.
Safe Rollback: If deployment fails, the previous release remains active.
Organized Releases: Each deployment is stored in a timestamped directory.

Step 1: Install Laravel Envoy

Explain how to install Laravel Envoy globally using Composer.

composer global require laravel/envoy

Ensure readers add Composer's global binaries to their system PATH if not already done.

export PATH="$PATH:$HOME/.composer/vendor/bin"

Or Install to your project dir

composer require laravel/envoy --dev

Step 2: Set Up SSH Access to Your Server

Explain how to set up SSH access to the server. Include steps for generating an SSH key and adding it to the server for password-less access.

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
ssh-copy-id username@your-server-ip

Test the connection:

ssh username@your-server-ip

Step 3: Create the Envoy Configuration File

Show how to create an envoy.blade.php file in the root of the Laravel project and explain its structure.

Example Configuration:

@servers(['web' => 'username@your-server-ip'])

@setup
    $repository = 'git@github.com:your-username/your-repo.git';
    $releases_dir = '/var/www/your-project/releases';
    $app_dir = '/var/www/your-project';
    $release = date('YmdHis');
    $new_release_dir = $releases_dir . '/' . $release;
@endsetup

@story('deploy')
    clone_repository
    run_composer
    update_symlinks
@endstory

@task('clone_repository', ['on' => 'web'])
    [ -d {{ $releases_dir }} ] || mkdir -p {{ $releases_dir }};
    git clone --branch=main {{ $repository }} {{ $new_release_dir }};
@endtask

@task('run_composer', ['on' => 'web'])
    cd {{ $new_release_dir }};
    composer install --optimize-autoloader --no-dev;
@endtask

@task('update_symlinks', ['on' => 'web'])
    ln -nfs {{ $new_release_dir }} {{ $app_dir }}/current;
    ln -nfs {{ $app_dir }}/shared/.env {{ $new_release_dir }}/.env;
@endtask

Explain each section:

@servers: Define remote servers.
@setup: Initialize variables for the deployment process.
@story: Sequence of tasks to execute.
@task: Individual steps like cloning the repository or running Composer.

Step 4: Deploy the Laravel Project

Explain how to run the deployment command using Envoy:

envoy run deploy

Highlight how Envoy connects via SSH and executes tasks in sequence.

Step 5: Test the Deployment

Guide readers on verifying the deployment:

Check the project directory on the server.
Ensure the symlinks are correctly pointing to the latest release.
Test the application in the browser.

Step 6: Add Cache Clearing and Maintenance Mode

Show how to enhance the script with cache clearing and maintenance mode commands.

Example Addition:

@task('clear_cache', ['on' => 'web'])
    php {{ $app_dir }}/current/artisan config:cache;
    php {{ $app_dir }}/current/artisan route:cache;
    php {{ $app_dir }}/current/artisan view:cache;
@endtask

@task('maintenance_mode', ['on' => 'web'])
    php {{ $app_dir }}/current/artisan down --message="Deployment in progress";
@endtask

Bonus: Rollback to Previous Release

Include an optional feature for rolling back to the previous release in case of failure.

Example Rollback Task:

@task('rollback', ['on' => 'web'])
    ln -nfs {{ $releases_dir }}/$(ls -t {{ $releases_dir }} | tail -n 2 | head -n 1) {{ $app_dir }}/current;
@endtask

Common Issues and Debugging Tips

Provide solutions to common problems like:

SSH authentication errors.
Missing permissions on the server.
Envoy not being recognized as a command.

"I hope this guide helps you simplify your Laravel deployments with Envoy. Let me know your thoughts or questions below! Don’t forget to follow for more Laravel tutorials."

References

Conclusion

Wrap up by emphasizing the power of automation in modern development workflows and inviting readers to share feedback or ask questions in the comments.

Laravel factory and seeder

Anas Hussain — Mon, 23 Dec 2024 04:39:58 +0000

1. Creating a Factory

Step 1: Generate the Factory

Run the following command to create a factory for your model:

php artisan make:factory ModelNameFactory --model=ModelName

Example:

php artisan make:factory DepartmentFactory --model=Department

This will create a file at database/factories/DepartmentFactory.php.

Step 2: Define the Factory

Open the factory file and define the data structure. Use realistic data for better testing.

namespace Database\Factories;

use App\Models\Department;
use Illuminate\Database\Eloquent\Factories\Factory;

class DepartmentFactory extends Factory
{
    protected $model = Department::class;

    public function definition()
    {
        return [
            'name' => $this->faker->word, // Generates a random department name
            'description' => $this->faker->sentence, // Short description
            'created_at' => now(),
            'updated_at' => now(),
        ];
    }
}

2. Creating a Seeder

Step 1: Generate the Seeder

Run the following command to create a seeder:

php artisan make:seeder SeederName

Example:

php artisan make:seeder DepartmentSeeder

This will create a file at database/seeders/DepartmentSeeder.php.

Step 2: Define the Seeder

In the seeder file, use the factory to generate records.

namespace Database\Seeders;

use App\Models\Department;
use Illuminate\Database\Seeder;

class DepartmentSeeder extends Seeder
{
    public function run()
    {
        // Generate 10 departments
        Department::factory(10)->create();
    }
}

3. Register the Seeder

Step 1: Add Seeder to DatabaseSeeder

In database/seeders/DatabaseSeeder.php, call the DepartmentSeeder:

namespace Database\Seeders;

use Illuminate\Database\Seeder;

class DatabaseSeeder extends Seeder
{
    public function run()
    {
        $this->call([
            DepartmentSeeder::class,
        ]);
    }
}

4. Run the Seeder

Run the following command to seed your database:

php artisan db:seed

To run a specific seeder:

php artisan db:seed --class=DepartmentSeeder

5. Professional Practices

Use Relationships in Factories If your model has relationships, define them in the factory:

   'user_id' => User::factory(), // Generates a user and assigns it to this model

Use Custom States Create states for specific variations of the model:

   public function admin()
   {
       return $this->state([
           'role' => 'admin',
       ]);
   }

Use it in seeders:

   Department::factory()->admin()->create();

Organize Seeders For large projects, organize seeders into modules:

   database/
   └── seeders/
       ├── Admin/
       │   ├── UserSeeder.php
       │   └── RoleSeeder.php
       ├── Product/
       │   └── ProductSeeder.php
       └── DepartmentSeeder.php

Testing with Factories Use factories in tests to generate test data:

   $department = Department::factory()->create();
   $this->assertDatabaseHas('departments', ['id' => $department->id]);

Clear and Seed For fresh testing, run:

   php artisan migrate:fresh --seed

6. Example Usage

If you have a Department model, you can now generate:

Random departments:

  Department::factory()->count(10)->create();

Custom departments:

  Department::factory()->create([
      'name' => 'Human Resources',
  ]);

DEV Community: Anas Hussain

Why Laravel's Service Container Feels Like Magic: Dependency Injection Explained

1. Hook & Problem Statement

2. Why This Pattern/Concept Exists

The Coupling Catastrophe

The Pain That Existed Before

Why Large Applications Need It

3. Real World Analogy

4. The Pain (Bad Design)

5. Solution Overview

Core Idea

Main Participants

Mental Model

Benefits

Trade-offs

6. UML Diagram

7. Vanilla PHP Example

Before Refactoring

After Refactoring

Step 1: Define Interfaces (The Contract)

Step 2: Create Implementations

Step 3: The Refactored Client

Step 4: The Manual Injector (The "Container")

8. Laravel Internal Example

The HTTP Kernel

The handle Method in Controllers

Service Providers

9. Real Laravel Application Example

Step 1: The Interface

Step 2: Concrete Implementations

Step 3: The Controller

Step 4: Binding in a Service Provider

10. SOLID Principles Mapping

11. Trade-offs

Benefits

Costs

When is it justified?

12. When NOT To Use It

3 Green Flags (USE IT)

3 Red Flags (AVOID IT)

13. Common Mistakes

1. Overengineering (The "Just in Case" Syndrome)

2. Confusing Service Providers with Business Logic

3. Using the Container as a Service Locator

4. Not Providing Default Values

14. Frequently Asked Interview Questions

Beginner/Intermediate

Senior/Architect

15. Interactive Practice Challenge

16. Final Mental Model

17. Related Concepts

Dependency Inversion Principle (DIP)

The Real-World Example: Imagine you buy a brand-new smartphone

❌ The Wrong Way: Depending directly on low-level tools (Violates DIP)

✅The Right Way: Inverting the dependency (Adheres to DIP)

Step 1: Create the Abstraction (The Blueprint)

Step 2: Make low-level tools adapt to the blueprint

Step 3: Inject the abstraction into the high-level class

Why this helps you

The 3 Main Confusions Cleared Up

1. Confusion: "Is Dependency Inversion the same thing as Dependency Injection?"

2. Confusion: "Does DIP mean every single new keyword in PHP is a sin?"

3. Confusion: "Who actually owns the interface?"

The Ultimate DIP Clean Code Check

The 3-Step Decision Matrix (How to Choose)

Summary for Decision Making

The Laravel Blueprint: Mastering DIP (example)

❌ The Junior Approach (Violates DIP)

The Laravel Mastery Approach (Adheres to DIP)

Step 1: Depend entirely on the Abstraction

Step 2: Swap the low-level details in .env

Step 3: How Laravel wires it up under the hood

Why this makes you a Laravel Master

Interface Segregation Principle (ISP)

The Real-World Example: Imagine you want to sign up for a local fitness center.

❌ The Wrong Way: The "Fat" Interface (Violates ISP)

✅The Right Way: Small, Focused Interfaces (Adheres to ISP)

Why this helps you

The 3 Main Confusions Cleared Up

1. Confusion: "Does ISP mean I can only have one method per interface?"

The `handle` Method in Controllers