README

用于与HAL API交互的PHP客户端。

安装

1. 通过Composer安装

您可以通过Composer安装此包。在终端运行以下命令

composer require amanank/hal-client

如果您还没有这样做，请确保在您的项目中包含Composer的autoload文件

require 'vendor/autoload.php';

2. 发布配置文件

安装包后，您可以使用以下Artisan命令发布配置文件

php artisan vendor:publish --tag=config --provider="Amanank\HalClient\Providers\HalClientServiceProvider"

这将创建一个名为 hal-client.php 的配置文件，位于您的 config 目录中。

注意

Laravel的自动发现功能将自动为您注册HalClientServiceProvider。您不需要在config/app.php文件中手动注册它。

3. 配置 hal-client.php

注册服务提供者后，您需要配置它。在您的config目录中创建一个名为hal-client.php的配置文件，内容如下

return [
    'base_uri' => env('HAL_API_BASE_URI', 'https://example.com/api/v1/'),
    'headers' => [
        'Authorization' => 'Bearer ' . env('HAL_API_TOKEN'),
        'Accept' => 'application/hal+json',
    ],
];

请确保在您的.env文件中设置HAL_API_BASE_URI和HAL_API_TOKEN环境变量

HAL_API_BASE_URI=https://api.example.com
HAL_API_TOKEN=your-api-token

4. 生成模型

要生成HAL API的模型，请在终端运行以下命令

# Clear the application cache to ensure that any configuration changes are properly loaded
php artisan config:cache

# Generate models based on your HAL API schema
php artisan hal:generate-models

# Update the Composer autoloader to include the new models
composer dump-autoload

这将根据您的HAL API模式生成必要的模型，并确保它们被正确地自动加载。

用法

基本用法

生成模型后，您可以直接从Amanank\HalClient\Models\Discovered命名空间使用它们，或者在您的App\Models命名空间中扩展它们。

直接使用模型

use Amanank\HalClient\Models\Discovered\User;
use Amanank\HalClient\Models\Discovered\Post;
use Amanank\HalClient\Models\Discovered\Tag;
use Amanank\HalClient\Models\Discovered\Comment;

// Create a new user
$user = new User();
$user->username = 'john.doe';
$user->email = 'john.doe@example.com';
$user->save();

// Create a new post
$post = new Post();
$post->title = 'My First Post';
$post->content = 'This is the content of my first post.';
$post->user()->associate($user);
$post->save();

// Create a new tag
$tag = new Tag();
$tag->name = 'PHP';
$tag->save();

// Create a new comment
$comment = new Comment();
$comment->content = 'Great post!';
$comment->post()->associate($post);
$comment->user()->associate($user);
$comment->save();

扩展模型

您还可以在您的App\Models命名空间中扩展生成的模型

namespace App\Models;

use Amanank\HalClient\Models\Discovered\User as DiscoveredUser;

class User extends DiscoveredUser {
    // Add your custom methods or properties here
}

创建和更新模型

use App\Models\User;
use App\Models\Post;
use App\Models\Tag;
use App\Models\Comment;

// Create a new user
$user = new User();
$user->username = 'john.doe';
$user->email = 'john.doe@example.com';
$user->save();

// Update a user
$user = User::find(1);
$user->email = 'new.email@example.com';
$user->save();

搜索模型

您可以使用Model::get方法获取模型，该方法接受参数$page = null、$size = null和$sort = null，并返回一个LengthAwarePaginator。

此外，您可以直接使用HAL API公开的任何搜索方法。例如，User::findByLastName返回一个集合，而User::getByEmail返回一个User或null。

use Amanank\HalClient\Models\Discovered\User;

// Get paginated users
$users = User::get($page = 1, $size = 10, $sort = 'username');

// Find users by last name
$usersByLastName = User::findByLastName('Doe');

// Get user by email
$userByEmail = User::getByEmail('john.doe@example.com');

处理关系

use App\Models\User;
use App\Models\Post;
use App\Models\Tag;
use App\Models\Comment;

// Get user's posts
$user = User::find(1);
$posts = $user->posts;

// Get post's comments
$post = Post::find(1);
$comments = $post->comments;

// Attach a tag to a post
$post = Post::find(1);
$tag = Tag::find(1);
$post->tags()->attach($tag);

// Detach a tag from a post
$post->tags()->detach($tag);

处理枚举

枚举位于Amanank\HalClient\Models\Discovered\Enums命名空间下，并以前缀模型名称命名，例如UserStatusEnum和PostStatusEnum。

use Amanank\HalClient\Models\Discovered\Enums\UserStatusEnum;
use App\Models\User;

// Set user status
$user = User::find(1);
$user->status = UserStatusEnum::ACTIVE;
$user->save();

// Get users with a specific status
$activeUsers = User::where('status', UserStatusEnum::ACTIVE)->get();

许可证

本项目采用MIT许可证。有关详细信息，请参阅LICENSE文件。

贡献

1. 将仓库Fork。
2. 创建一个新的分支（git checkout -b feature-branch）。
3. 进行更改。
4. 提交更改（git commit -am '添加新功能'）。
5. 将更改推送到分支（git push origin feature-branch）。
6. 创建一个新的Pull Request。

支持

如果您有任何问题或需要支持，请在GitHub仓库中创建一个issue。