Micrus Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require avris/micrus
   

   Add the service provider to config/app.php:

   'providers' => [
       // ...
       Avris\Micrus\MicrusServiceProvider::class,
   ],
   

2. Basic Routing Define routes in routes/web.php:

   use Avris\Micrus\Facades\Micrus;
   
   Micrus::get('/', 'HomeController@index');
   Micrus::post('/submit', 'FormController@store');
   

3. First Controller Create a controller (e.g., app/Http/Controllers/HomeController.php):

   namespace App\Http\Controllers;
   
   use Avris\Micrus\Http\Controllers\Controller;
   
   class HomeController extends Controller {
       public function index() {
           return response()->json(['message' => 'Hello, Micrus!']);
       }
   }
   

4. Run the Server

   php artisan serve
   

   Test with curl http://localhost:8000.

Where to Look First

• Documentation: Check the GitLab repo for API docs (if available).
• Core Classes:
  • Avris\Micrus\Facades\Micrus (Facade for routing).
  • Avris\Micrus\Http\Controllers\Controller (Base controller).
  • Avris\Micrus\Support\Helper (Utility functions).
• Config: Publish config with php artisan vendor:publish --provider="Avris\Micrus\MicrusServiceProvider".

First Use Case: REST API Endpoint

// routes/web.php
Micrus::get('/api/users', 'UserController@index');
Micrus::post('/api/users', 'UserController@store');

// app/Http/Controllers/UserController.php
class UserController extends Controller {
    public function index() {
        return response()->json(User::all());
    }

    public function store(Request $request) {
        $user = User::create($request->all());
        return response()->json($user, 201);
    }
}

Implementation Patterns

Routing Patterns

1. Resourceful Routing Use Micrus::resource() for RESTful conventions:

   Micrus::resource('posts', 'PostController');
   

   Generates: GET|HEAD /posts, POST /posts, GET /posts/{id}, etc.

2. Middleware Integration Attach middleware to routes:

   Micrus::get('/admin', 'AdminController@dashboard')
       ->middleware('auth:admin');
   

3. Route Groups Group routes with shared prefixes/middleware:

   Micrus::prefix('api/v1')->group(function () {
       Micrus::get('/users', 'UserController@index');
       Micrus::post('/users', 'UserController@store');
   });
   

Controller Patterns

1. Dependency Injection Inject services into controllers:

   class UserController extends Controller {
       protected $userService;
   
       public function __construct(UserService $userService) {
           $this->userService = $userService;
       }
   }
   

2. Request Validation Use Laravel’s built-in validation:

   public function store(Request $request) {
       $validated = $request->validate([
           'name' => 'required|string|max:255',
           'email' => 'required|email',
       ]);
       // ...
   }
   

3. View Responses Return Blade views:

   public function index() {
       return view('users.index', ['users' => User::all()]);
   }
   

Common Workflows

1. API Development

   • Use response()->json() for API responses.
   • Leverage Micrus::apiResource() for API-specific resource routing.

2. Form Handling

   • Use Micrus::post() for form submissions.
   • Redirect with return redirect()->route('route.name').

3. Authentication

   • Integrate with Laravel’s auth system:

     Micrus::get('/dashboard', 'DashboardController@index')
         ->middleware('auth');
     

4. Error Handling

   • Define custom error handlers in app/Exceptions/Handler.php.
   • Use throw new \Avris\Micrus\Http\Exceptions\HttpResponseException($response).

Gotchas and Tips

Pitfalls

1. Namespace Conflicts

   • Ensure controllers are in App\Http\Controllers or update autoloading:

     composer dump-autoload
     

2. Route Caching

   • Clear cached routes after changes:

     php artisan route:clear
     

3. Middleware Order

   • Middleware runs in registration order. Use ->middleware() carefully:

     // Wrong: Overrides previous middleware
     Micrus::get('/test')->middleware('auth')->middleware('log');
     
     // Correct: Appends middleware
     Micrus::get('/test')->middleware(['auth', 'log']);
     

4. CSRF Protection

   • Enable CSRF for web routes (disabled by default for APIs):

     Micrus::middleware('web')->group(function () {
         Micrus::post('/form', 'FormController@submit');
     });
     

Debugging Tips

1. Route Listing Dump all routes:

   php artisan route:list
   

2. Request Dumping Use dd($request->all()) or dd($request) in controllers.

3. Error Logging Configure config/logging.php for detailed logs.

4. Facade Debugging Check if the facade is bound correctly:

   dd(app('micrus'));
   

Extension Points

1. Custom Facade Bindings Extend the facade in AppServiceProvider:

   public function boot() {
       \Avris\Micrus\Facades\Micrus::extend('custom', function () {
           return new CustomRouter();
       });
   }
   

2. Service Provider Hooks Override Micrus’s service provider:

   class CustomMicrusServiceProvider extends \Avris\Micrus\MicrusServiceProvider {
       public function register() {
           parent::register();
           // Custom logic
       }
   }
   

3. View Composers Use Laravel’s composers for shared data:

   View::composer('*', function ($view) {
       $view->with('sharedData', collect());
   });
   

4. Event Listeners Listen to Micrus events (if supported):

   event(new \Avris\Micrus\Events\RouteRegistered($route));
   

Performance Tips

1. Route Model Binding Use implicit binding:

   Micrus::get('/users/{user}', 'UserController@show');
   

   Ensure User model implements RouteKeyName or getRouteKey().

2. Caching Cache routes in production:

   php artisan route:cache
   

3. Lazy Loading Avoid eager loading in controllers; use lazy collections:

   return User::where('active', true)->cursor(); // For large datasets
   

4. Queue Jobs Offload heavy tasks:

   public function store(Request $request) {
       ProcessUser::dispatch($request->all());
       return response()->json(['message' => 'Processing...']);
   }