splash/openapi

A Collection of tools for OpenAPI Connectors

2.0.0 2024-02-13 17:37 UTC

Requires

• php: ^8.0
• ext-json: *
• jms/serializer: ^3
• nategood/httpful: ^0.2|^0.3
• splash/php-bundle: dev-master

Requires (Dev)

• api-platform/core: *
• badpixxel/php-sdk: ~2.0
• splash/toolkit: dev-master

MIT

• Splash Sync
• BadPixxel

Published on Packagist.org on 2024-02-13 16:42 UTC

README

Splash OpenApi

A flexible PHP library for building REST API clients with support for multiple formats: JSON, JSON-LD (API Platform), and HAL+JSON.

Features

• Multi-format support: JSON, JSON-LD (Hydra), HAL+JSON
• Visitor pattern: Clean abstraction for different API formats
• Action-based architecture: Configurable CRUD operations with OptionsResolver
• Metadata integration: Works with Splash Metadata for automatic field parsing
• Extensible: Easy to add custom actions, visitors, and transformers

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                      CONNECTOR                               │
└─────────────────────────┬───────────────────────────────────┘
                          │ uses
                          ▼
┌─────────────────────────────────────────────────────────────┐
│              VISITOR (implements VisitorInterface)           │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │ JsonVisitor │  │JsonLdVisitor│  │ HalVisitor  │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────┬───────────────────────────────────┘
                          │ delegates to
                          ▼
┌─────────────────────────────────────────────────────────────┐
│               ACTIONS (implement ActionInterface)            │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │
│  │   List   │ │   Load   │ │  Create  │ │  Update  │       │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘       │
└─────────────────────────────────────────────────────────────┘

Supported API Formats

Format	Content-Type	Collection Key	Pagination
JSON	application/json	Root array	page, itemsPerPage
JSON-LD	application/ld+json	member	view (Hydra)
HAL	application/hal+json	_embedded	_links
GraphQL	application/json	edges[].node	Cursor (first/after)

Note: GraphQL support is planned.

Installation

composer require splash/openapi

Quick Example

Create a Splash Object that syncs data via REST API:

namespace App\Objects;

use App\Connector\MyConnector;
use App\Models\Api\Product;
use Splash\OpenApi\Models\Objects\AbstractRestAndMetadataObject;

class ProductObject extends AbstractRestAndMetadataObject
{
    /**
     * @var Product
     */
    protected object $object;

    public function __construct(MyConnector $connector)
    {
        parent::__construct(
            $connector->getVisitor(Product::class),
            $connector->getMetadataAdapter(),
            Product::class
        );
    }
}

The AbstractRestAndMetadataObject provides all CRUD operations automatically via the MetadataActionsTrait.

Documentation

Full documentation is available in the docs/ folder:

Section	Description
Getting Started	Installation and quick start guide
Models	API models and serializer groups
Visitors	JSON, JSON-LD, and HAL visitor guides
Actions	Action configuration and transformers
Migration Guide	Migrating from v2 to v3

Requirements

• PHP 8.3+
• Symfony Components (OptionsResolver, Serializer, PropertyAccess)

Contributing

Any Pull requests are welcome!

This module is part of SplashSync project.

License

This project is licensed under the MIT License - see the LICENSE file for details.