Laravel Asana Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require christhompsontldr/laravel-asana
   

2. Publish Config (optional but recommended):

   php artisan vendor:publish --provider="ChrisThompsonTLDR\Asana\AsanaServiceProvider"
   

   • Edit config/asana.php with your Asana API token and workspace ID.

3. First Use Case: Fetch a project by ID in a controller or service:

   use ChrisThompsonTLDR\Asana\Facades\Asana;
   
   $project = Asana::projects()->find('1234567890123456');
   return response()->json($project);
   

Key Starting Points

• Facade: Use Asana::projects(), Asana::tasks(), etc., for direct API access.
• Artisan Commands:
  • List custom fields: php artisan asana:custom-fields [workspace_id].
  • Fetch users: php artisan asana:users.

Implementation Patterns

Core Workflows

1. CRUD Operations:

   // Create a task
   $task = Asana::tasks()->create([
       'name' => 'Complete API integration',
       'projects' => ['1234567890123456'],
       'custom_fields' => ['1234567890123456' => 'value']
   ]);
   
   // Update a task
   Asana::tasks()->update('1234567890123456', ['name' => 'Updated task']);
   
   // Delete a task
   Asana::tasks()->delete('1234567890123456');
   

2. Querying Data:

   // Get tasks with pagination
   $tasks = Asana::tasks()->all(['opt_fields' => 'name,projects', 'limit' => 10]);
   
   // Filter tasks by project
   $tasks = Asana::tasks()->where('projects', '1234567890123456')->get();
   

3. Custom Fields:

   • Use the asana:custom-fields command to fetch GIDs for your workspace.
   • Reference them in API calls:

     $task = Asana::tasks()->create([
         'custom_fields' => ['1234567890123456' => 'High']
     ]);
     

4. Event Listeners:

   • Listen for API responses (e.g., logging or analytics):

     // In EventServiceProvider
     protected $listen = [
         'ChrisThompsonTLDR\Asana\Events\AsanaResponse' => [
             'App\Listeners\LogAsanaResponse',
         ],
     ];
     

Integration Tips

• Service Layer: Encapsulate Asana logic in a service class to avoid facade clutter:

  class AsanaTaskService {
      public function createTask(array $data) {
          return Asana::tasks()->create($data);
      }
  }
  

• Error Handling: Wrap API calls in try-catch blocks:

  try {
      $task = Asana::tasks()->find('1234567890123456');
  } catch (\ChrisThompsonTLDR\Asana\Exceptions\AsanaException $e) {
      Log::error($e->getMessage());
      return response()->json(['error' => 'Failed to fetch task'], 500);
  }
  

• Rate Limiting: Asana enforces rate limits. Cache responses aggressively:

  $tasks = Cache::remember("asana_tasks_{$projectId}", now()->addHours(1), function() use ($projectId) {
      return Asana::tasks()->where('projects', $projectId)->get();
  });
  

Gotchas and Tips

Pitfalls

1. Deprecated Laravel Support:

   • The package supports Laravel 5.x/6.x only. Avoid using with newer versions (e.g., Laravel 8+).
   • Workaround: Fork the package or use a community-maintained fork if needed.

2. Custom Field GIDs:

   • Asana’s API requires Global IDs (GIDs) for custom fields, not names. Use the asana:custom-fields command to fetch them:

     php artisan asana:custom-fields WORKSPACE_ID
     

   • Gotcha: Hardcoding GIDs in code violates DRY principles. Store them in a config file or database.

3. Pagination Quirks:

   • The package doesn’t handle pagination automatically. Use ?opt_fields and ?limit for partial data:

     $tasks = Asana::tasks()->all(['limit' => 50, 'opt_fields' => 'name,due_on']);
     

   • Tip: Implement manual pagination in your service layer if needed.

4. Webhooks:

   • The package doesn’t support Asana’s webhooks. For real-time updates, use Asana’s native webhook system and sync data via a queue job.

5. Rate Limit Headers:

   • Asana returns X-RateLimit-Remaining headers. Parse them to avoid hitting limits:

     $response = Asana::tasks()->all();
     $remainingRequests = $response->headers->get('X-RateLimit-Remaining');
     

Debugging

1. Enable Debugging:

   • Set debug to true in config/asana.php to log raw API responses:

     'debug' => env('ASANA_DEBUG', false),
     

   • Check Laravel logs (storage/logs/laravel.log) for errors.

2. Common Errors:

   • 401 Unauthorized: Verify your API token in config/asana.php.
   • 404 Not Found: Double-check GIDs (e.g., projects, tasks, custom fields).
   • Validation Errors: Asana returns detailed error messages in the errors array of the response.

Extension Points

1. Custom API Methods:

   • Extend the package by creating a decorator:

     class CustomAsana extends \ChrisThompsonTLDR\Asana\Asana {
         public function customMethod() {
             return $this->get('custom/endpoint');
         }
     }
     

   • Bind it in a service provider:

     $this->app->bind('asana', function() {
         return new CustomAsana(config('asana'));
     });
     

2. Add New Resources:

   • The package follows a resource-based pattern (projects, tasks). Add support for unsupported resources (e.g., stories, sections) by extending the base class:

     class AsanaStories extends \ChrisThompsonTLDR\Asana\Resources\BaseResource {
         protected $endpoint = 'stories';
     }
     

   • Register it in the service provider:

     Asana::extend('stories', function() {
         return new AsanaStories(config('asana'));
     });
     

3. Testing:

   • Mock the Asana facade in tests:

     $this->mock(\ChrisThompsonTLDR\Asana\Facades\Asana::class)->shouldReceive('tasks')->andReturnSelf();
     $this->mock()->shouldReceive('find')->andReturn($mockTask);