Ctaroutes Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require muhaiminshihab/ctaroutes
   

   Publish the config (if needed) via:

   php artisan vendor:publish --provider="MuhaiminShihab\CtaRoutes\CtaRoutesServiceProvider"
   

2. First Use Case: Access the package’s routes directly in your browser:

   • Clear cache: GET /cta-routes/cache-clear
   • Run migrations: GET /cta-routes/migrate
   • Create storage link: GET /cta-routes/storage-link

   Verify the route works by checking the response (e.g., 200 OK with Artisan command output).

3. Where to Look First:

   • Config File: config/ctaroutes.php (if published) for customization (e.g., route prefixes, middleware).
   • Service Provider: app/Providers/CtaRoutesServiceProvider.php to extend or override routes.
   • Route List: Run php artisan route:list | grep cta-routes to inspect available endpoints.

Implementation Patterns

Usage Patterns

1. Browser-Based Artisan Commands: Use the package to expose Artisan commands as HTTP routes for non-technical users (e.g., QA, DevOps) or automated workflows (e.g., CI/CD hooks). Example:

   // Trigger via browser or API client
   $response = Http::get('/cta-routes/migrate');
   

2. Middleware Integration: Restrict access to specific routes using Laravel middleware (e.g., auth, admin):

   // In CtaRoutesServiceProvider.php
   Route::get('/cta-routes/migrate', [CtaRoutesController::class, 'migrate'])
       ->middleware(['auth', 'can:run-migrations']);
   

3. Custom Routes: Extend the package by adding new routes in the service provider:

   // Add a custom route for `queue:work`
   Route::get('/cta-routes/queue-work', function () {
       Artisan::call('queue:work');
       return response()->json(['status' => 'Queue worker started']);
   });
   

4. API Endpoints: Wrap routes in API resources for programmatic access:

   Route::prefix('api/cta')->group(function () {
       Route::get('/migrate', [CtaRoutesController::class, 'migrate']);
   });
   

5. Workflow Automation: Chain routes in a deployment script or CI pipeline:

   curl -X GET http://your-app.test/cta-routes/migrate-fresh
   curl -X GET http://your-app.test/cta-routes/config-cache
   

Integration Tips

• Environment Checks: Disable routes in config/ctaroutes.php for production if unsafe:

  'enabled' => env('APP_ENV') !== 'production',
  

• Logging: Log Artisan command outputs for debugging:

  // In CtaRoutesController.php
  Artisan::call('migrate');
  Log::info('Migrations ran via CtaRoutes', ['output' => Artisan::output()]);
  

• Rate Limiting: Protect routes from abuse with Laravel’s throttle middleware:

  Route::get('/cta-routes/migrate', ...)->middleware('throttle:10,1');
  

Gotchas and Tips

Pitfalls

1. Permission Issues:

   • Symlink Creation: The storage:link route may fail if the storage/app/public directory lacks write permissions. Fix with:

     chmod -R 775 storage/
     

   • Artisan Commands: Some commands (e.g., migrate:fresh) require database access. Ensure your Laravel app’s .env is configured correctly.

2. Route Conflicts:

   • The package’s routes are prefixed with /cta-routes/, but ensure no existing routes or packages (e.g., laravel-debugbar) conflict. Check with:

     php artisan route:list
     

3. Output Handling:

   • Artisan commands output to STDOUT by default. For silent execution, suppress output:

     Artisan::call('cache:clear', [], null, null, true); // 5th param = silent
     

4. Database Transactions:

   • Commands like migrate:fresh drop tables without rolling back. Test in a staging environment first.

5. Caching Side Effects:

   • Routes like config:cache or cache:clear may cause unexpected behavior if misused (e.g., clearing cache mid-request). Use sparingly in production.

Debugging

• Check Artisan Output: Redirect output to a file for debugging:

  Artisan::call('migrate', [], function ($output) {
      file_put_contents(storage_path('logs/ctaroutes.log'), $output);
  });
  

• Verify Middleware: Ensure middleware (e.g., web or api) is applied to routes. Add ->middleware('web') if needed.

• Test Locally: Use Laravel’s --env=testing flag to avoid unintended side effects:

  php artisan --env=testing cta-routes:migrate
  

Extension Points

1. Custom Commands: Extend the package by adding new routes in CtaRoutesServiceProvider.php:

   Route::get('/cta-routes/custom-command', function () {
       Artisan::call('your:custom-command');
   });
   

2. Middleware Overrides: Override the default middleware for specific routes:

   Route::get('/cta-routes/migrate', ...)->middleware('admin');
   

3. Response Formatting: Standardize responses by wrapping Artisan output in JSON:

   return response()->json([
       'success' => true,
       'output' => Artisan::output(),
       'command' => 'migrate'
   ]);
   

4. Environment-Specific Routes: Dynamically enable/disable routes based on environment:

   if (app()->environment('local')) {
       Route::get('/cta-routes/debug', ...);
   }
   

5. Event Listeners: Trigger events after commands run (e.g., notify Slack):

   event(new CtaRouteExecuted('migrate', Artisan::output()));