Cli Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require atlas/cli --dev
   

   • Add to require-dev in composer.json to avoid production bloat.

2. Publish Config (if needed):

   php artisan vendor:publish --provider="Atlas\Cli\CliServiceProvider"
   

   • Check config/atlas-cli.php for default settings (e.g., API endpoints, auth tokens).

3. First Use Case: Run a basic Atlas command (e.g., list projects):

   php artisan atlas:projects
   

   • Verify authentication via .env (e.g., ATLAS_API_TOKEN=your_token_here).

Where to Look First

• Documentation: ./docs/getting-started.md Focus on:
  • Authentication (API tokens, OAuth).
  • Command structure (e.g., atlas:projects, atlas:deploy).
• Service Provider: Atlas\Cli\CliServiceProvider for binding/boot logic.
• Commands: Browse src/Commands/ for available actions (e.g., ProjectsCommand, DeployCommand).

Implementation Patterns

Workflows

1. Authentication Workflow:

   • Store tokens in .env (e.g., ATLAS_API_TOKEN).
   • Use Atlas\Cli\Services\AuthService to validate tokens before commands run.
   • Example:

     $auth = app(AuthService::class);
     if (!$auth->isAuthenticated()) {
         throw new \RuntimeException("Authentication required.");
     }
     

2. Command Integration:

   • Extend base commands (e.g., Atlas\Cli\Commands\BaseCommand) for custom logic.
   • Example: Add a atlas:custom-action command:

     namespace App\Console\Commands;
     use Atlas\Cli\Commands\BaseCommand;
     
     class CustomAtlasCommand extends BaseCommand {
         protected $signature = 'atlas:custom-action {argument}';
         protected $description = 'Custom Atlas CLI action';
     
         public function handle() {
             $this->info("Running custom action for: {$this->argument}");
             // Use Atlas\Cli\Services\AtlasService for API calls
         }
     }
     

   • Register in App\Console\Kernel.php:

     protected $commands = [
         Commands\CustomAtlasCommand::class,
     ];
     

3. API Interaction:

   • Use Atlas\Cli\Services\AtlasService to wrap API calls (e.g., getProjects(), deploy()).
   • Example:

     $projects = app(AtlasService::class)->getProjects();
     $this->table(array_keys($projects[0]), $projects);
     

4. Event-Driven Extensions:

   • Listen for Atlas events (e.g., atlas.deploy.started) via Laravel’s event system.
   • Example in EventServiceProvider:

     protected $listen = [
         'atlas.deploy.started' => [DeployLogger::class, 'log'],
     ];
     

Integration Tips

• Laravel Mix/Webpack: Use Atlas CLI commands in package.json scripts for CI/CD (e.g., npm run deploy triggers php artisan atlas:deploy).
• Artisan Scheduling: Schedule Atlas commands in app/Console/Kernel.php:

  $schedule->command('atlas:check-updates')->daily();
  

• Testing: Mock AtlasService in PHPUnit:

  $this->app->instance(AtlasService::class, Mockery::mock(AtlasService::class));
  

Gotchas and Tips

Pitfalls

1. Authentication Caching:

   • Tokens may not auto-refresh. Implement a refreshToken() method in AuthService if needed.
   • Example:

     if ($auth->isTokenExpired()) {
         $auth->refreshToken();
     }
     

2. Rate Limiting:

   • Atlas API may throttle requests. Add retries with exponential backoff:

     use Symfony\Component\HttpClient\RetryableHttpClient;
     $client = new RetryableHttpClient($httpClient, [
         'max_retries' => 3,
         'delay_factor' => 2,
     ]);
     

3. Command Output:

   • Avoid mixing info()/error() with raw API responses. Use table() or json() for structured output:

     $this->table(['ID', 'Name'], $projects);
     

4. Deprecated Methods:

   • Check changelog.md for removed features (e.g., AtlasService::oldMethod()).

Debugging

1. Enable Verbose Logging: Set ATLAS_DEBUG=true in .env to log API requests/responses.

   • Example log entry:

     [Atlas] GET /api/projects | Status: 200 | Response: {"data": [...]}
     

2. Common Errors:

   • 401 Unauthorized: Verify ATLAS_API_TOKEN in .env.
   • 500 Server Error: Check Atlas status page or wrap API calls in try-catch:

     try {
         $response = $atlasService->deploy();
     } catch (\Atlas\Cli\Exceptions\AtlasException $e) {
         $this->error($e->getMessage());
     }
     

3. API Response Parsing:

   • Atlas may return paginated data. Use AtlasService::getPaginatedResults():

     $projects = $atlasService->getPaginatedResults('/projects', ['limit' => 50]);
     

Extension Points

1. Custom API Endpoints: Extend AtlasService to add methods for non-standard endpoints:

   namespace App\Services;
   use Atlas\Cli\Services\AtlasService;
   
   class CustomAtlasService extends AtlasService {
       public function getCustomData() {
           return $this->get('/custom-endpoint');
       }
   }
   

   Bind in AppServiceProvider:

   $this->app->bind(CustomAtlasService::class, function ($app) {
       return new CustomAtlasService($app->make(AtlasService::class));
   });
   

2. Command Pre/Post Hooks: Use Laravel’s registering and registered events for commands:

   // In AppServiceProvider
   Atlas\Cli\Commands\BaseCommand::registering(function ($command) {
       $command->setLaravel($this->app);
   });
   

3. Configuration Overrides: Override config/atlas-cli.php for environment-specific settings (e.g., staging vs. production endpoints):

   'endpoints' => [
       'api' => env('ATLAS_API_URL', 'https://api.atlas.example.com'),
   ],
   

4. Testing Helpers: Create a trait for testing Atlas commands:

   trait TestsAtlasCommands {
       protected function callAtlasCommand($command, array $args = []) {
           return $this->artisan("atlas:{$command}", $args)
               ->expectsQuestion('Confirm?', 'yes')
               ->assertExitCode(0);
       }
   }