Sdk Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require styleci/sdk
   

   Add the SDK to your composer.json autoload if not using PSR-4:

   "autoload": {
       "psr-4": {
           "App\\": "app/",
           "StyleCI\\SDK\\": "vendor/styleci/sdk/src/"
       }
   }
   

2. First Use Case: Authenticating with StyleCI

   use StyleCI\SDK\StyleCI;
   
   $styleCI = new StyleCI([
       'token' => env('STYLECI_TOKEN'),
       'base_url' => env('STYLECI_BASE_URL', 'https://styleci.io/api/v1'),
   ]);
   

3. Key Classes to Explore

   • StyleCI (main client)
   • StyleCI\SDK\Exceptions\StyleCIException (error handling)
   • StyleCI\SDK\Resources\Project (project operations)
   • StyleCI\SDK\Resources\Check (check status)

4. First API Call

   $projects = $styleCI->projects()->all();
   

Implementation Patterns

Workflow: CI/CD Integration

1. Trigger Checks on Push

   // In a GitHub Actions/Laravel Forge hook
   $styleCI->checks()->create([
       'project_id' => $projectId,
       'branch' => 'main',
       'target' => 'full',
   ]);
   

2. Polling for Results

   $check = $styleCI->checks()->find($checkId);
   while ($check->status === 'queued') {
       sleep(5);
       $check = $styleCI->checks()->find($checkId);
   }
   

Workflow: Project Management

1. Syncing Local Projects

   $styleCI->projects()->create([
       'name' => 'My Laravel App',
       'git_url' => 'https://github.com/user/repo.git',
       'branch' => 'main',
       'style_preset' => 'laravel',
   ]);
   

2. Batch Updates

   $projects = $styleCI->projects()->all();
   foreach ($projects as $project) {
       $styleCI->projects()->update($project->id, [
           'style_preset' => 'psr12',
       ]);
   }
   

Laravel-Specific Patterns

1. Service Provider Binding

   // app/Providers/StyleCIServiceProvider.php
   public function register()
   {
       $this->app->singleton(StyleCI::class, function ($app) {
           return new StyleCI([
               'token' => config('services.styleci.token'),
               'base_url' => config('services.styleci.base_url'),
           ]);
       });
   }
   

2. Artisan Command for Checks

   // app/Console/Commands/RunStyleCI.php
   public function handle()
   {
       $styleCI = app(StyleCI::class);
       $check = $styleCI->checks()->create([
           'project_id' => $this->option('project'),
           'branch' => $this->option('branch'),
       ]);
       $this->info("Triggered check: {$check->id}");
   }
   

3. Event Listeners for Git Hooks

   // Listen to repo:push (Laravel Forge)
   public function handle()
   {
       $styleCI = app(StyleCI::class);
       $styleCI->checks()->create([
           'project_id' => config('styleci.project_id'),
           'branch' => request()->input('branch'),
       ]);
   }
   

Gotchas and Tips

Debugging

1. Enable Debug Mode

   $styleCI = new StyleCI([
       'token' => env('STYLECI_TOKEN'),
       'debug' => true, // Enable debug logging
   ]);
   

   • Logs will appear in storage/logs/laravel.log.

2. Handling Rate Limits

   • The SDK throws StyleCI\SDK\Exceptions\RateLimitException.
   • Implement exponential backoff:

     try {
         $styleCI->projects()->all();
     } catch (RateLimitException $e) {
         sleep($e->getRetryAfter());
         retry();
     }
     

Configuration Quirks

1. Base URL Overrides

   • Use STYLECI_BASE_URL for self-hosted instances:

     STYLECI_BASE_URL=https://your-styleci.example.com/api/v1
     

2. Token Scopes

   • Ensure your token has read:projects, write:checks scopes if needed.

Extension Points

1. Custom HTTP Client

   • Override the default Guzzle client:

     $styleCI = new StyleCI([
         'token' => env('STYLECI_TOKEN'),
         'http_client' => new CustomGuzzleClient(),
     ]);
     

2. Response Transformers

   • Extend StyleCI\SDK\Resources\Resource to modify responses:

     class CustomProject extends \StyleCI\SDK\Resources\Project
     {
         public function transform($data)
         {
             $data['formatted_name'] = strtolower($data['name']);
             return parent::transform($data);
         }
     }
     

3. Mocking for Tests

   • Use StyleCI\SDK\Mock\StyleCIMock:

     $mock = new StyleCIMock();
     $mock->shouldReceive('projects->all')->andReturn([...]);
     

Pitfalls

1. Deprecated Endpoints

   • The SDK was last updated in 2021; verify endpoints like /checks exist in your StyleCI version.

2. Pagination Handling

   • Always check $resource->getNextPageUrl() for paginated results:

     $projects = $styleCI->projects()->all();
     while ($nextPage = $projects->getNextPageUrl()) {
         $projects = $styleCI->getHttpClient()->get($nextPage);
     }
     

3. Webhook Validation

   • StyleCI webhooks use X-StyleCI-Signature. Validate in Laravel middleware:

     public function handle($request, Closure $next)
     {
         $styleCI = app(StyleCI::class);
         if ($styleCI->validateWebhook($request)) {
             return $next($request);
         }
         abort(403);
     }