README

RESTORM

一个用于通过HTTP REST API持久化数据的REST ORM库。受Doctrine启发，RESTORM提供实体管理器，以处理实体到和从REST API的持久化和加载。

功能概述

• 💾 从RESTful API加载和保存实体
• 👥 管理来自多个API的数据
• 🔃 管理实体之间的单向和双向关系
• 💤 无需费力地懒加载关联实体
• 🎈 循环中自动调用分页实体
• 📝 标量、对象和内嵌实体类型

文档内容

1. 安装
2. 快速入门
3. 基本用法
   1. 创建实体
   2. 创建配置文件
   3. 初始化管理器
4. 内部
   1. "查找" 工作流程
   2. "持久化" 工作流程
5. 参考
   1. 配置参考

安装

要安装RESTORM，运行以下composer命令

composer install thesalegroup/restorm

如果您还没有这样做，请将composer的自动加载文件添加到您的项目代码中

require __DIR__ . '/../vendor/autoload.php';

快速入门

以下示例可以作为使用RESTORM设置新项目的参考。有关更多信息，请参阅本指南的其余部分，它将链接到更多文档和参考。

<?php

// Use the composer autoloader to load in RESTORM
require __DIR__ . '/../vendor/autoload.php';

use TheSaleGroup\Restorm\Configuration\Configuration;
use TheSaleGroup\Restorm\EntityManager;
use App\Entity\Post;

// Create a new Configuration instance based on our configuration
$configPath = '../config/restorm.yml';
$configuration = Configuration::buildFromYaml($configPath);

// Create a new EntityManager from our Configuration instance
$entityManager = EntityManager::createFromConfiguration($configuration);

// Fetch all the posts from the API
$posts = $entityManager->getRepository(Post::class)->findAll();

// Loop over the collection of posts to see their data
foreach($posts as $post) {
    
    // Instances of Author are lazy loaded when you need them.
    $author = $post->getAuthor() // Returns an instance of Author

    // No request is made to the API for the author until you request
    // data that wasn't available in the initial request.

    // The following request will not trigger a new call …
    $authorId = $author->getId();

    // …whereas this one will quietly populate the rest of Author
    $authorName = $author->getName();
    
}

基本用法

以下步骤将向您展示RESTORM在项目中的非常简单的用法。我们将设置RESTORM与位于https://example.com/api的人工端点通信，该端点提供RESTful API。对于此示例，我们将创建一组非常简单的实体，这些实体对博客很有用。这些将包括一个具有关联Author实体的Post实体。

创建实体

首先，我们将为我们的实体创建一些类。实体是一个由RESTORM管理的资源对象。实体具有属性，这些属性从RESTful API调用中填充，以及您希望在其中包含的任何其他方法或逻辑。让我们创建一个简单的Post类

<?php
# src/Entity/Post.php

namespace App\Entity;

class Post {

    private $id;

    private $title;

    public $content;

    private $author;

    public function getId(): ?int
    {
        return $this->id;
    }

    public function getAuthor(): ?Author
    {
        return $this->author;
    }

    public function getTitle(): ?string
    {
        return $this->title;
    }

}

实体不需要扩展RESTORM中的任何接口或类 - 任何类都可以成为实体。请注意，Post::$id、Post::$title和Post::$author都是私有属性 - 这不会影响RESTORM管理这些字段的能力，因为它通过反射管理属性。

在我们的Post实体中，"ID"、"title"和"content"都将是从API获取的简单标量值，但"author"不同；尽管这将是API中的整数，代表作者的ID，但我们希望这个属性填充Author的实例。在我们创建配置来管理此字段和其他字段之前，让我们也创建Author类

<?php
# src/Entity/Author.php

namespace App\Entity;

class Author {

    private $id;

    private $name;

    public function getId(): ?int
    {
        return $this->id;
    }

    public function getName(): ?string
    {
        return $this->name;
    }
}

创建配置文件

现在我们已经定义了实体类，是时候创建配置文件了。为此，我们需要知道我们需要调用哪些URL来获取实体数据以及需要在实体中填充哪些属性。让我们假设在这个示例中，我们需要与位于https://example.com/api的RESTful端点通信。我们将添加以下配置文件，该文件将设置连接细节和实体映射

connections:

    # Define a connection which describes where we get entities from
    default:

        # The base URI is going to include the /api path as this
        # is universal for all endpoints on this connection
        base_uri: https://example.com/api

        # Let RESTORM know what the parameters are for using
        # pagination with list endpoints
        pagination_parameters:
            page_param: page
            per_page_param: per_page

# Define the Post and Author entities
entity_mappings:

    # Use the fully qualified entity class name as the key
    App\Entity\Post:

        # Use our "default" connection we registered above
        connection: default

        # Use the internal entity repository for querying
        # for entities
        repository_class: TheSaleGroup\Restorm\EntityRepository

        # Define the paths to each of the actions used for
        # getting and saving entities
        paths:
            list: /posts
            get: /posts/{id}
            post: /posts/new
            patch: /posts/{id}/edit
            delete: posts/{id}

        # List our properties
        properties:
            id:
                # Let RESTORM know that the id is the identifier
                identifier: true
                type: integer
            title:
                type: string
                unique: true
            content:
                type: string
                # The content property is called "html_content"
                # in the API so map that to the "content"
                # property in the entity
                map_from: html_content
            # Relate a Post entity to an Author entity
            author:
                # We will set the type as "entity"…
                type: entity
                # …and set the entity class
                entity: Project\Entity\Author
    Project\Entity\Author:
        connection: default
        repository_class: TheSaleGroup\Restorm\EntityRepository
        paths:
            list: /authors
            get: /authors/{username}
            post: /authors
            patch: /authors/{username}
            delete: /authors/{username}
        properties:
            id:
                identifier: true
                type: integer
            name:
                type: string

您可以在此处查看完整的配置参考

初始化管理器

实体管理器是RESTORM的核心。它控制实体在连接之间传输，并连接每个内部组件。让我们创建一个简单的脚本，用于创建一个新的EntityManager并获取所有帖子

<?php

// Use the composer autoloader to load in RESTORM
require __DIR__ . '/../vendor/autoload.php';

use TheSaleGroup\Restorm\Configuration\Configuration;
use TheSaleGroup\Restorm\EntityManager;
use App\Entity\Post;

// Create a new Configuration instance based on our configuration
$configPath = '../config/restorm.yml';
$configuration = Configuration::buildFromYaml($configPath);

// Create a new EntityManager from our Configuration instance
$entityManager = EntityManager::createFromConfiguration($configuration);

在实例化EntityManager之后，现在可以使用它来获取实体

// Fetch all the posts from the API
$posts = $entityManager->getRepository(Post::class)->findAll();

// Loop over the collection of posts to see their data
foreach($posts as $post) {
    
    // Instances of Author are lazy loaded when you need them.
    $author = $post->getAuthor() // Returns an instance of Author

    // No request is made to the API for the author until you request
    // data that wasn't available in the initial request.

    // The following request will not trigger a new call …
    $authorId = $author->getId();

    // …whereas this one will quietly populate the rest of Author
    $authorName = $author->getName();
    
}