SharpAPI Laravel 整合指南

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

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

---

目錄

1. 先決條件
2. 設定 Laravel 項目
3. 安裝 SharpAPI PHP 用戶端
4. 配置
   • 環境變數
5. 使用 SharpAPI 進行驗證
6. 進行 API 呼叫
   • 範例：產生職位描述
7. 處理回應
8. 錯誤處理
9. 測試整合
10. 進階用法
    • 非同步請求
    • 快取回應
11. 結論
12. 支持
13. 許可證

---

先決條件

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

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

---

設定 Laravel 項目

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

1. 透過 Composer 安裝 Laravel

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

1. 導覽至專案目錄

   cd laravel-ai-integration-guide

1. 送達申請

   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 檔案進行特定於環境的配置。

1. 開啟 .env 檔案

位於 Laravel 專案的根目錄中。

1. 新增您的 SharpAPI API 金鑰

   SHARP_API_KEY=your_actual_sharpapi_api_key_here

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

1. 在程式碼中存取環境變數

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

   $apiKey = env('SHARP_API_KEY');

---

使用 SharpAPI 進行身份驗證

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

1. 初始化 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;
       }
   }

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

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

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

1. 在控制器中使用服務

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

1. 定義路線

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

   use App\Http\Controllers\SharpApiController;

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

---

進行 API 呼叫

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

範例：產生職位描述

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

1. 定義路線

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

1. 存取端點

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

---

處理回應

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

1. 理解反應結構

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

1. 訪問結果

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

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

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

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

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

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

---

License

This project is licensed under the MIT License.

---

以上是SharpAPI Laravel 整合指南的詳細內容。更多資訊請關注PHP中文網其他相關文章！