Welcome to the SharpAPI Laravel Integration Guide! This repository provides a comprehensive, 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
   • Environment Variables
5. Authentication with SharpAPI
6. Making API Calls
   • Example: Generating a Job Description
7. Handling Responses
8. Error Handling
9. Testing the Integration
10. Advanced Usage
    • Asynchronous Requests
    • Caching Responses
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

1. Navigate to the Project Directory

   cd laravel-ai-integration-guide

1. Serve the Application

   php artisan serve

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

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

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');

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.

   client = new SharpApiService(env('SHARP_API_KEY'));
       }

       public function getClient()
       {
           return $this->client;
       }
   }

1. Binding the Service in a Service Provider (Optional)

This allows you to inject the service wherever needed.

   app->singleton(SharpApiClient::class, function ($app) {
               return new SharpApiClient();
           });
       }

       public function boot()
       {
           //
       }
   }

1. Using the Service in a Controller

   sharpApi = $sharpApi->getClient();
       }

       public function ping()
       {
           $response = $this->sharpApi->ping();
           return response()->json($response);
       }
   }

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']);

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

   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());
       }
   }

1. Define the Route

   Route::get('/sharpapi/generate-job-description', [SharpApiController::class, 'generateJobDescription']);

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
       }
   }

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

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);
       }
   }

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);
       }
   }

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);
   }

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.

   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...
   }

1. Running Tests

Execute your tests using PHPUnit.

   ./vendor/bin/phpunit

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

Run the necessary migrations.

   php artisan queue:table
   php artisan migrate

1. Creating a Job

   php artisan make:job ProcessSharpApiRequest

   params = $params;
       }

       public function handle(SharpApiClient $sharpApi)
       {
           $statusUrl = $sharpApi->generateJobDescription($this->params);
           $resultJob = $sharpApi->fetchResults($statusUrl);
           // Handle the result...
       }
   }

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.']);
   }

1. Running the Queue Worker

   php artisan queue:work

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));
   }

1. Invalidating Cache

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

   Cache::forget('job_description_' . md5(json_encode($jobDescriptionParams)));

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 [email protected].

License

This project is licensed under the MIT License.