DEV Community

Cover image for SharpAPI Laravel Integration Guide
Dawid Makowski
Dawid Makowski

Posted on • Edited on

SharpAPI Laravel Integration Guide

#laravel #php #webdev #ai

Welcome to the SharpAPI Laravel Integration Guide! This step-by-step tutorial on how to integrate SharpAPI into your next Laravel AI application. Whether you're looking to enhance your app with AI-powered features or automate workflows, this guide will walk you through the entire process, from authentication to making API calls and handling responses.

Article published also as a Github repository at https://github.com/sharpapi/laravel-ai-integration-guide.

Table of Contents

  1. Prerequisites
  2. Setting Up the Laravel Project
  3. Installing the SharpAPI PHP Client
  4. Configuration
  5. Authentication with SharpAPI
  6. Making API Calls
  7. Handling Responses
  8. Error Handling
  9. Testing the Integration
  10. Advanced Usage
  11. Conclusion
  12. Support
  13. License

Prerequisites

Before you begin, ensure you have met the following requirements:

  • PHP: >= 8.1
  • Composer: Dependency manager for PHP
  • Laravel: Version 9 or higher
  • SharpAPI Account: Obtain an API key from SharpAPI.com
  • Basic Knowledge of Laravel: Familiarity with Laravel framework and MVC architecture

Setting Up the Laravel Project

If you already have a Laravel project, you can skip this step. Otherwise, follow these instructions to create a new Laravel project.

  1. Install Laravel via Composer 
   composer create-project --prefer-dist laravel/laravel laravel-ai-integration-guide
Enter fullscreen mode Exit fullscreen mode
  1. Navigate to the Project Directory 
   cd laravel-ai-integration-guide
Enter fullscreen mode Exit fullscreen mode
  1. Serve the Application 
   php artisan serve
Enter fullscreen mode Exit fullscreen mode

The application will be accessible at http://localhost:8000.

Installing the SharpAPI PHP Client

To interact with SharpAPI, you'll need to install the SharpAPI PHP client library.

Require the SharpAPI Package via Composer

composer require sharpapi/sharpapi-laravel-client
php artisan vendor:publish --tag=sharpapi-laravel-client
Enter fullscreen mode Exit fullscreen mode

Configuration

Environment Variables

Storing sensitive information like API keys in environment variables is a best practice. Laravel uses the .env file for environment-specific configurations.

  1. Open the .env File

Located in the root directory of your Laravel project.

  1. Add Your SharpAPI API Key 
   SHARP_API_KEY=your_actual_sharpapi_api_key_here
Enter fullscreen mode Exit fullscreen mode

Note: Replace your_actual_sharpapi_api_key_here with your actual SharpAPI API key.

  1. Accessing Environment Variables in Code

Laravel provides the env helper function to access environment variables.

   $apiKey = env('SHARP_API_KEY');
Enter fullscreen mode Exit fullscreen mode

Authentication with SharpAPI

Authentication is required to interact with SharpAPI's endpoints securely.

  1. Initialize the SharpAPI Client

Create a service or use it directly in your controllers.

   <?php

   namespace App\Services;

   use SharpAPI\SharpApiService;

   class SharpApiClient
   {
       protected $client;

       public function __construct()
       {
           $this->client = new SharpApiService(env('SHARP_API_KEY'));
       }

       public function getClient()
       {
           return $this->client;
       }
   }
Enter fullscreen mode Exit fullscreen mode
  1. Binding the Service in a Service Provider (Optional)

This allows you to inject the service wherever needed.

   <?php

   namespace App\Providers;

   use Illuminate\Support\ServiceProvider;
   use App\Services\SharpApiClient;

   class AppServiceProvider extends ServiceProvider
   {
       public function register()
       {
           $this->app->singleton(SharpApiClient::class, function ($app) {
               return new SharpApiClient();
           });
       }

       public function boot()
       {
           //
       }
   }
Enter fullscreen mode Exit fullscreen mode
  1. Using the Service in a Controller 
   <?php

   namespace App\Http\Controllers;

   use Illuminate\Http\Request;
   use App\Services\SharpApiClient;

   class SharpApiController extends Controller
   {
       protected $sharpApi;

       public function __construct(SharpApiClient $sharpApi)
       {
           $this->sharpApi = $sharpApi->getClient();
       }

       public function ping()
       {
           $response = $this->sharpApi->ping();
           return response()->json($response);
       }
   }
Enter fullscreen mode Exit fullscreen mode
  1. Defining Routes

Add routes to routes/web.php or routes/api.php:

   use App\Http\Controllers\SharpApiController;

   Route::get('/sharpapi/ping', [SharpApiController::class, 'ping']);
Enter fullscreen mode Exit fullscreen mode

Making API Calls

Once authenticated, you can start making API calls to various SharpAPI endpoints. Below are examples of how to interact with different endpoints.

Example: Generating a Job Description

  1. Create a Job Description Parameters DTO 
   <?php

   namespace App\Http\Controllers;

   use Illuminate\Http\Request;
   use App\Services\SharpApiClient;
   use SharpAPI\Dto\JobDescriptionParameters;

   class SharpApiController extends Controller
   {
       protected $sharpApi;

       public function __construct(SharpApiClient $sharpApi)
       {
           $this->sharpApi = $sharpApi->getClient();
       }

       public function generateJobDescription()
       {
           $jobDescriptionParams = new JobDescriptionParameters(
               "Software Engineer",
               "Tech Corp",
               "5 years",
               "Bachelor's Degree in Computer Science",
               "Full-time",
               [
                   "Develop software applications",
                   "Collaborate with cross-functional teams",
                   "Participate in agile development processes"
               ],
               [
                   "Proficiency in PHP and Laravel",
                   "Experience with RESTful APIs",
                   "Strong problem-solving skills"
               ],
               "USA",
               true,   // isRemote
               true,   // hasBenefits
               "Enthusiastic",
               "Category C driving license",
               "English"
           );

           $statusUrl = $this->sharpApi->generateJobDescription($jobDescriptionParams);
           $resultJob = $this->sharpApi->fetchResults($statusUrl);

           return response()->json($resultJob->getResultJson());
       }
   }
Enter fullscreen mode Exit fullscreen mode
  1. Define the Route 
   Route::get('/sharpapi/generate-job-description', [SharpApiController::class, 'generateJobDescription']);
Enter fullscreen mode Exit fullscreen mode
  1. Accessing the Endpoint

Visit http://localhost:8000/sharpapi/generate-job-description to see the generated job description.

Handling Responses

SharpAPI responses are typically encapsulated in job objects. To handle these responses effectively:

  1. Understanding the Response Structure 
   {
       "id": "uuid",
       "type": "JobType",
       "status": "Completed",
       "result": {
           // Result data
       }
   }
Enter fullscreen mode Exit fullscreen mode
  1. Accessing the Result

Use the provided methods to access the result data.

   $resultJob = $this->sharpApi->fetchResults($statusUrl);
   $resultData = $resultJob->getResultObject(); // As a PHP object
   // or
   $resultJson = $resultJob->getResultJson(); // As a JSON string
Enter fullscreen mode Exit fullscreen mode
  1. Example Usage in Controller 
   public function generateJobDescription()
   {
       // ... (initialize and make API call)

       if ($resultJob->getStatus() === 'Completed') {
           $resultData = $resultJob->getResultObject();
           // Process the result data as needed
           return response()->json($resultData);
       } else {
           return response()->json(['message' => 'Job not completed yet.'], 202);
       }
   }
Enter fullscreen mode Exit fullscreen mode

Error Handling

Proper error handling ensures that your application can gracefully handle issues that arise during API interactions.

  1. Catching Exceptions

Wrap your API calls in try-catch blocks to handle exceptions.

   public function generateJobDescription()
   {
       try {
           // ... (initialize and make API call)

           $resultJob = $this->sharpApi->fetchResults($statusUrl);
           return response()->json($resultJob->getResultJson());
       } catch (\Exception $e) {
           return response()->json([
               'error' => 'An error occurred while generating the job description.',
               'message' => $e->getMessage()
           ], 500);
       }
   }
Enter fullscreen mode Exit fullscreen mode
  1. Handling API Errors

Check the status of the job and handle different statuses accordingly.

   if ($resultJob->getStatus() === 'Completed') {
       // Handle success
   } elseif ($resultJob->getStatus() === 'Failed') {
       // Handle failure
       $error = $resultJob->getResultObject()->error;
       return response()->json(['error' => $error], 400);
   } else {
       // Handle other statuses (e.g., Pending, In Progress)
       return response()->json(['message' => 'Job is still in progress.'], 202);
   }
Enter fullscreen mode Exit fullscreen mode

Testing the Integration

Testing is crucial to ensure that your integration with SharpAPI works as expected.

  1. Writing Unit Tests

Use Laravel's built-in testing tools to write unit tests for your SharpAPI integration.

   <?php

   namespace Tests\Feature;

   use Tests\TestCase;
   use App\Services\SharpApiClient;
   use SharpAPI\Dto\JobDescriptionParameters;

   class SharpApiTest extends TestCase
   {
       protected $sharpApi;

       protected function setUp(): void
       {
           parent::setUp();
           $this->sharpApi = new SharpApiClient();
       }

       public function testPing()
       {
           $response = $this->sharpApi->ping();
           $this->assertEquals('OK', $response['status']);
       }

       public function testGenerateJobDescription()
       {
           $jobDescriptionParams = new JobDescriptionParameters(
               "Backend Developer",
               "InnovateTech",
               "3 years",
               "Bachelor's Degree in Computer Science",
               "Full-time",
               ["Develop APIs", "Optimize database queries"],
               ["Proficiency in PHP and Laravel", "Experience with RESTful APIs"],
               "USA",
               true,
               true,
               "Professional",
               "Category B driving license",
               "English"
           );

           $statusUrl = $this->sharpApi->generateJobDescription($jobDescriptionParams);
           $resultJob = $this->sharpApi->fetchResults($statusUrl);

           $this->assertEquals('Completed', $resultJob->getStatus());
           $this->assertNotEmpty($resultJob->getResultObject());
       }

       // Add more tests for other methods...
   }
Enter fullscreen mode Exit fullscreen mode
  1. Running Tests

Execute your tests using PHPUnit.

   ./vendor/bin/phpunit
Enter fullscreen mode Exit fullscreen mode

Advanced Usage

Asynchronous Requests

For handling multiple API requests concurrently, consider implementing asynchronous processing using Laravel Queues.

  1. Setting Up Queues

Configure your queue driver in the .env file.

   QUEUE_CONNECTION=database
Enter fullscreen mode Exit fullscreen mode

Run the necessary migrations.

   php artisan queue:table
   php artisan migrate
Enter fullscreen mode Exit fullscreen mode
  1. Creating a Job 
   php artisan make:job ProcessSharpApiRequest
Enter fullscreen mode Exit fullscreen mode 
   <?php

   namespace App\Jobs;

   use Illuminate\Bus\Queueable;
   use Illuminate\Contracts\Queue\ShouldQueue;
   use Illuminate\Foundation\Bus\Dispatchable;
   use Illuminate\Queue\InteractsWithQueue;
   use Illuminate\Queue\SerializesModels;
   use App\Services\SharpApiClient;
   use SharpAPI\Dto\JobDescriptionParameters;

   class ProcessSharpApiRequest implements ShouldQueue
   {
       use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

       protected $params;

       public function __construct(JobDescriptionParameters $params)
       {
           $this->params = $params;
       }

       public function handle(SharpApiClient $sharpApi)
       {
           $statusUrl = $sharpApi->generateJobDescription($this->params);
           $resultJob = $sharpApi->fetchResults($statusUrl);
           // Handle the result...
       }
   }
Enter fullscreen mode Exit fullscreen mode
  1. Dispatching the Job 
   use App\Jobs\ProcessSharpApiRequest;

   public function generateJobDescriptionAsync()
   {
       $jobDescriptionParams = new JobDescriptionParameters(
           // ... parameters
       );

       ProcessSharpApiRequest::dispatch($jobDescriptionParams);
       return response()->json(['message' => 'Job dispatched successfully.']);
   }
Enter fullscreen mode Exit fullscreen mode
  1. Running the Queue Worker 
   php artisan queue:work
Enter fullscreen mode Exit fullscreen mode

Caching Responses

To optimize performance and reduce redundant API calls, implement caching.

  1. Using Laravel's Cache Facade 
   use Illuminate\Support\Facades\Cache;

   public function generateJobDescription()
   {
       $cacheKey = 'job_description_' . md5(json_encode($jobDescriptionParams));
       $result = Cache::remember($cacheKey, 3600, function () use ($jobDescriptionParams) {
           $statusUrl = $this->sharpApi->generateJobDescription($jobDescriptionParams);
           $resultJob = $this->sharpApi->fetchResults($statusUrl);
           return $resultJob->getResultJson();
       });

       return response()->json(json_decode($result, true));
   }
Enter fullscreen mode Exit fullscreen mode
  1. Invalidating Cache

When the underlying data changes, ensure to invalidate the relevant cache.

   Cache::forget('job_description_' . md5(json_encode($jobDescriptionParams)));
Enter fullscreen mode Exit fullscreen mode

Conclusion

Integrating SharpAPI into your Laravel application unlocks a myriad of AI-powered functionalities, enhancing your application's capabilities and providing seamless workflow automation. This guide has walked you through the essential steps, from setting up authentication to making API calls and handling responses. With the examples and best practices provided, you're well-equipped to leverage SharpAPI's powerful features in your Laravel projects.

Support

If you encounter any issues or have questions regarding the integration process, feel free to open an issue on the GitHub repository or contact our support team at contact@sharpapi.com.

Top comments (0)

Read next

xxzeroxx profile image

PHP 8 News: Constructor Property Promotion

Antonio Silva -

maximsaplin profile image

OpenAI o3 - Thinking Fast and Slow

Maxim Saplin -

mdarifulhaque profile image

1760. Minimum Limit of Balls in a Bag

MD ARIFUL HAQUE -

anony9653 profile image

Why Regular Website Maintenance is Crucial for Your Business

coder9653 -