Beyond Fat Controllers: A Guide to the Laravel Repository Pattern

1. Impossible to Test: How do you test the PDF generation logic on line 800? You can't. You have to run the entire controller, mock a full HTTP request, fake an authenticated user, and maybe even hit a real database. Developers stop writing tests, which means more bugs.
   
   
2. Impossible to Maintain: The class has 10 jobs. To change one small thing (like an email subject), you have to hunt through 1,500 lines of unrelated code, praying you don't break something else.
   
   
3. You Can't Change Your Database (Tight Coupling): The controller is full of Order::where(...) and User::create(...). It's "married" to your Eloquent models.
   
   
   • What if your boss says, "We need to add a Redis cache to all order queries to speed things up?" You have to find every single query in that giant file and manually add caching logic.
     
     
   • What if they say, "We're moving all order data to an external API?" Your entire controller is now useless. You have to rewrite it all from scratch.
     
     
4. No Reusable Code (DRY Violation): Your OrderController has 100 lines of logic for creating an order. What happens when your new API also needs to create an order? The developer will just copy-paste those 100 lines into Api/OrderController.php. Now you have two sources of truth, and a bug fixed in one is forgotten in the other.
   
   
5. Constant Merge Conflicts: In a team, Developer A works on the validation (lines 50-150) while Developer B works on the PDF logic (lines 800-900). When you both try to merge, you get constant, painful merge conflicts on the same file, even though your tasks were totally unrelated.
   
   

• The Controller (The Waiter ): This is your new, "thin" controller. Its only job is to take the customer's Request (the order) and return a Response (the food). It doesn't know how to cook.
  
  
• The Service (The Head Chef ): This is where all the business logic (the "recipe") lives. The Waiter gives the order to the Chef. The Chef knows the steps: "First, chop the vegetables, then sear the meat, then notify the manager..."
  
  
• The Repository (The Pantry Clerk ): This is the star of today's show. Its only job is to get things from the pantry (the database). The Chef doesn't go to the pantry; they just tell the Pantry Clerk, "Get me 5 onions" or "Save this new dish."
  
  

• ⚡ Solar panels
  
  
• 🏭 A nuclear plant
  
  
• 💨 A wind farm
  
  
• 🔋 A battery
  
  

<?php
// app/Contracts/Repositories/UniversityRepositoryInterface.php

namespace App\Contracts\Repositories;

use Illuminate.Database\Eloquent\Collection;
use Illuminate\Pagination\LengthAwarePaginator;
use App\Models\University; // Make sure to import your model

interface UniversityRepositoryInterface
{
    /**
     * Finds universities by name for a quick search.
     */
    public function searchByName(string $name, int $limit = 20): Collection;

    /**
     * Gets a single university with all its details.
     */
    public function findWithDetails(int $id): ?University;

    /**
     * Gets a paginated list of universities based on filters.
     */
    public function getFiltered(array $filters, int $perPage = 15): LengthAwarePaginator;
}

<?php
// app/Repositories/UniversityRepository.php

namespace App\Repositories;

use App\Contracts\Repositories\UniversityRepositoryInterface;
use App\Models\University;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Pagination\LengthAwarePaginator;

class UniversityRepository implements UniversityRepositoryInterface
{
    public function searchByName(string $name, int $limit = 20): Collection
    {
        return University::select(['id', 'name', 'logo'])
            ->where('name', 'like', "%{$name}%")
            ->limit($limit)
            ->get();
    }
    
    public function findWithDetails(int $id): ?University
    {
        return University::with(['country', 'courses', 'gallery'])
            ->find($id);
    }
    
    public function getFiltered(array $filters, int $perPage = 15): LengthAwarePaginator
    {
        $query = University::query();
        
        if (isset($filters['country_id'])) {
            $query->where('country_id', $filters['country_id']);
        }
        
        if (isset($filters['ranking_min'])) {
            $query->where('ranking', '>=', $filters['ranking_min']);
        }
        
        // ... any other filters ...
        
        return $query->paginate($perPage);
    }
}

<?php
// app/Services/UniversitySearchService.php

namespace App\Services;

use App\Contracts\Repositories\UniversityRepositoryInterface;

class UniversitySearchService
{
    // We depend on the "Contract" (Interface), not the "Employee" (Class)
    public function __construct(
        private UniversityRepositoryInterface $repository
    ) {}
    
    public function searchByName(string $term, int $limit = 20): array
    {
        // The Chef just follows the recipe.
        $universities = $this->repository->searchByName($term, $limit);
        
        // Business logic: Format the data for the API
        return [
            'status' => true,
            'data' => $universities->map(fn($uni) => [
                'id' => $uni->id,
                'name' => $uni->name,
                'logo' => $uni->logo
            ]),
            'total' => $universities->count()
        ];
    }
    
    public function getFilteredUniversities(array $filters, int $perPage = 15): array
    {
        $universities = $this->repository->getFiltered($filters, $perPage);
        
        // Business logic: Format paginated data for the API
        return [
            'status' => true,
            'data' => $universities->items(),
            'pagination' => [
                'current_page' => $universities->currentPage(),
                'total' => $universities->total(),
                'per_page' => $universities->perPage()
            ]
        ];
    }
}

<?php
// app/Providers/RepositoryServiceProvider.php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use App\Contracts\Repositories\UniversityRepositoryInterface;
use App\Repositories\UniversityRepository;

class RepositoryServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // This is the "binding"
        $this->app->bind(
            UniversityRepositoryInterface::class,
            UniversityRepository::class
        );
    }
}

<?php
// bootstrap/providers.php
return [
    App\Providers\AppServiceProvider::class,
    App\Providers\RepositoryServiceProvider::class, // <-- Add this line
];

<?php
// app/Http/Controllers/Api/UniversityController.php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Services\UniversitySearchService; // The "Chef"
use Illuminate\Http\Request;
use Illuminate\Http\JsonResponse;

class UniversityController extends Controller
{
    // The "Waiter" only knows the "Chef"
    public function __construct(
        private UniversitySearchService $searchService
    ) {}
    
    public function search(Request $request): JsonResponse
    {
        // 1. Take the order and validate it
        $data = $request->validate([
            'search' => 'required|string|min:2|max:100',
            'limit' => 'sometimes|integer|min:1|max:50'
        ]);
        
        // 2. Give the order to the Chef
        $result = $this->searchService->searchByName(
            $data['search'],
            $data['limit'] ?? 20
        );
        
        // 3. Return the food to the customer
        return response()->json($result);
    }
}

1. Create a new "employee" (Repository):
   
   

1. 
   

2. <?php
   // app/Repositories/ApiUniversityRepository.php
   class ApiUniversityRepository implements UniversityRepositoryInterface
   {
       public function searchByName(string $name, int $limit = 20): Collection
       {
           // Call the external API
           $response = Http::get("https://api.universities.com/search", [
               'q' => $name, 'limit' => $limit
           ]);
           // (Note: you'd map this to a Collection)
           return collect($response->json()['data'])->map(fn($item) => (object)$item); 
       }
   
       // ... implement other contract methods ...
   }
   
   

3. 
   Change one line in your RepositoryServiceProvider.php:
   
   

1. 
   

2. public function register(): void
   {
       $this->app->bind(
           UniversityRepositoryInterface::class,
           // UniversityRepository::class // --- OLD
           ApiUniversityRepository::class   // +++ NEW
       );
   }
   
   

<?php
// tests/Unit/UniversitySearchServiceTest.php

use App\Contracts\Repositories\UniversityRepositoryInterface;
use App\Services\UniversitySearchService;
use Illuminate\Support\Collection;
use Mockery;
use Tests\TestCase;

class UniversitySearchServiceTest extends TestCase
{
    public function test_can_search_universities_by_name()
    This test runs in milliseconds and doesn't need a database.    {
        // 1. "Mock" the contract. We create a FAKE employee.
        $mockRepository = Mockery::mock(UniversityRepositoryInterface::class);
        
        // 2. Tell the fake employee what to do.
        $mockRepository->shouldReceive('searchByName') // When called...
            ->once() // ...one time...
            ->with('Harvard', 10) // ...with these arguments...
            ->andReturn(new Collection([ // ...return this fake data.
                (object)['id' => 1, 'name' => 'Harvard University', 'logo' => 'harvard.png']
            ]));
            
        // 3. Give the "Chef" (Service) the FAKE employee.
        $service = new UniversitySearchService($mockRepository);
        $result = $service->searchByName('Harvard', 10);
        
        // 4. Test the Chef's recipe (the data formatting)
        $this->assertTrue($result['status']);
        $this->assertEquals('Harvard University', $result['data'][0]['name']);
        $this.assertEquals(1, $result['total']);
    }
}

1. You create CachedUniversityRepository.
   
   
2. It also implements UniversityRepositoryInterface.
   
   
3. Inside, it takes the UniversityRepository as a dependency.
   
   
4. Its logic is: "First, check Redis for this query. If I find it, return it. If not, ask the real UniversityRepository to get it, save it to Redis, then return it."
   
   
5. You just change your binding in the provider to CachedUniversityRepository, and your entire application is now cached without the Service or Controller ever knowing.
   
   

1. - You are building large, complex applications.
2. 
   
3. - You need to write comprehensive unit tests.
4. 
   
5. - You are working in a team (interfaces are clear contracts for other developers).
6. 
   
7. - Your data source might change (e.g., move from Eloquent to an API, or add a cache layer).

• - You are building a very simple CRUD-only application.
  
  
• - You are prototyping and need to be extremely fast.
  
  
• - You're 100% sure the app will never grow and you'll never write tests (which is rare!).
  
  

• Testable (Easy to mock and test in isolation)
  
  
• Flexible (Switch implementations without breaking code)
  
  
• Maintainable (Clear contracts and separation of concerns)
  
  
• Professional (Follows industry best practices and SOLID principles)