SharpAPI Laravel 整合指南-php教程-PHP中文網

SharpAPI Laravel Integration Guide

歡迎來到SharpAPI Laravel 整合指南！該儲存庫提供了有關如何將 SharpAPI 整合到下一個 Laravel AI 應用程式中的全面的逐步教學。無論您是想透過**人工智慧支援的功能**還是自動化工作流程來增強您的應用程序，本指南都將引導您完成從身份驗證到進行API 呼叫和處理響應的整個過程。

文章也作為 Github 儲存庫發佈在 https://github.com/sharpapi/laravel-ai-integration-guide。

先決條件

開始之前，請確保您已滿足以下要求：

PHP：>= 8.1
Composer：PHP 的依賴管理器
Laravel：版本 9 或更高版本
SharpAPI 帳號：從 SharpAPI.com 取得 API 金鑰
Laravel基礎知識：熟悉Laravel框架與MVC架構

設定 Laravel 項目

如果你已經有Laravel項目，可以跳過這一步。否則，請按照以下說明建立一個新的 Laravel 專案。

透過 Composer 安裝 Laravel


   composer create-project --prefer-dist laravel/laravel laravel-ai-integration-guide

登入後複製


   cd laravel-ai-integration-guide

登入後複製

送達申請


   php artisan serve

登入後複製

可以透過 http://localhost:8000 存取該應用程式。

安裝 SharpAPI PHP 用戶端

要與 SharpAPI 交互，您需要安裝 SharpAPI PHP 用戶端程式庫。

需要透過 Composer 取得 SharpAPI 套件


composer require sharpapi/sharpapi-laravel-client
php artisan vendor:publish --tag=sharpapi-laravel-client

登入後複製

配置

環境變數

在環境變數中儲存 API 金鑰等敏感資訊是最佳實務。 Laravel 使用 .env 檔案進行特定於環境的配置。

開啟 .env 檔案

位於 Laravel 專案的根目錄中。

新增您的 SharpAPI API 金鑰


   SHARP_API_KEY=your_actual_sharpapi_api_key_here

登入後複製

注意：將此處的 your_actual_sharpapi_api_key_key_替換為您實際的 SharpAPI API 金鑰。

在程式碼中存取環境變數

Laravel 提供了 env 輔助函數來存取環境變數。


   $apiKey = env('SHARP_API_KEY');

登入後複製

使用 SharpAPI 進行身份驗證

需要進行身份驗證才能安全地與 SharpAPI 端點互動。

初始化 SharpAPI 用戶端

建立服務或直接在控制器中使用它。


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

登入後複製

將服務綁定到服務提供者（可選）

這允許您在需要的地方注入服務。


   <?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()
       {
           //
       }
   }

登入後複製

在控制器中使用服務


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

登入後複製

定義路線

將路由加入routes/web.php或routes/api.php：


   use App\Http\Controllers\SharpApiController;

   Route::get('/sharpapi/ping', [SharpApiController::class, 'ping']);

登入後複製

進行 API 呼叫

經過驗證後，您可以開始對各種 SharpAPI 端點進行 API 呼叫。以下是如何與不同端點互動的範例。

範例：產生職位描述

建立作業描述參數 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());
       }
   }

登入後複製

定義路線


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

登入後複製

存取端點

造訪 http://localhost:8000/sharpapi/generate-job-description 查看產生的職位說明。

處理回應

SharpAPI 回應通常封裝在作業物件中。要有效處理這些回應：

理解反應結構


   {
       "id": "uuid",
       "type": "JobType",
       "status": "Completed",
       "result": {
           // Result data
       }
   }

登入後複製

訪問結果

使用提供的方法存取結果資料。


   $resultJob = $this->sharpApi->fetchResults($statusUrl);
   $resultData = $resultJob->getResultObject(); // As a PHP object
   // or
   $resultJson = $resultJob->getResultJson(); // As a JSON string

登入後複製

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.

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

登入後複製

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.

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

登入後複製

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.

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

登入後複製

Creating a Job


   php artisan make:job ProcessSharpApiRequest

登入後複製


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

登入後複製

Dispatching the Job


   use App\Jobs\ProcessSharpApiRequest;

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

       ProcessSharpApiRequest::dispatch($jobDescriptionParams);
       return response()->json(['message' => 'Job dispatched successfully.']);
   }

登入後複製

Running the Queue Worker


   php artisan queue:work

登入後複製

Caching Responses

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

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

登入後複製

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 contact@sharpapi.com.