search

xtend-packages / rest-presenter

Kickstart your Laravel development with our API Starter Kits & Generators.
https://rest-presenter.com
MIT License
66 stars 6 forks source link

readme

RESTPresenter

Latest Version on Packagist PHP from Packagist GitHub License GitHub Tests Action Status GitHub Code Style Action Status GitHub Code Style Action Status Total Downloads

Join our Discord

Introduction

RESTPresenter is a powerful, lightweight package designed to streamline Laravel API development. It integrates seamlessly with Laravel API Resources and Spatie's Data objects, making API creation and management effortless.

With RESTPresenter, you can:

RESTPresenter enhances your Laravel projects with powerful tools for efficient and secure API development.

Installation

To get started with RESTPresenter, you need to meet the following requirements:

Install the package via composer:

composer require xtend-packages/rest-presenter

Filament Plugin Integration

Manage your RESTPresenter resources directly from Filament with our dedicated plugin. This integration allows you to generate user tokens, manage your API resources, and more.

Plugin Installation

To install the RESTPresenter Filament plugin, run:

php artisan rest-presenter:filament --install

This command will prompt you to auto-commit changes to your Git repository. If you choose not to commit, you can manually commit the changes yourself. The Sanctum StarterKit is automatically installed during this process. For more details, see Sanctum StarterKit.

Export API Collection

To generate your API collection, run:

php artisan rest-presenter:generate-api-collection

By default, this command generates a Postman collection. If you prefer Insomnia, switch by setting the following in your .env file:

REST_PRESENTER_EXPORT_PROVIDER=insomnia

For a full list of configuration options, see Configuration.

Uninstall

To uninstall the RESTPresenter Filament plugin, run:

php artisan rest-presenter:filament --uninstall

This command will prompt you to auto-commit and revert changes to your Git repository. If you choose not to commit, you can manually commit the changes yourself.

RESTPresenter Panel

The new RESTPresenter panel serves as a dashboard, offering a comprehensive overview and management interface for your API collection.

RESTPresenter

You can access the RESTPresenter panel by navigating to /rest-presenter in your browser. the path is configurable in the .env file see Configuration for more details.

RESTPresenter panel link has now conveniently been added to the user menu for all your filament panels.

Features include:

Coming Soon: Test Coverage and Reports, just one of many features in active development.

Endpoint Authentication & Security

By default, all endpoints are publicly available without Sanctum middleware, protected by a security API key which you can update via REST_PRESENTER_AUTH_API_KEY in your .env file.

You can make any endpoint authenticated by updating the isAuthenticated property in the resource controller. This will automatically add the Sanctum middleware to the endpoint.

<?php

class CustomerResourceController extends ResourceController
{
    protected static string $model = Customer::class;

    public static bool $isAuthenticated = true;

    // ... rest of the resource controller
}

Generated Files

The following directories with generated files will be created:

Filament Test Suite

Tests are generated for each resource in the Filament test suite.

Warning: To prevent overriding your database, update phpunit.xml with the following:

<env name="DB_CONNECTION" value="sqlite"/>
<env name="DB_DATABASE" value=":memory:"/>

RESTPresenter Package

Key Features

Planned Features

Check out our Roadmap for upcoming features and improvements. Feel free to open an issue for suggestions or feature requests. Join us on Discord to start a discussion and stay updated on the latest news.

What Makes This Package Unique?

RESTPresenter is more than just a CRUD generator. It offers:

So What Are Presenters?

Presenters allow you to transform data before it's sent to the client, enabling modifications without altering API resources. This is particularly useful for transforming data for specific endpoints.

To use a presenter, add the header property X-REST-PRESENTER: PresenterName to your request. RESTPresenter will automatically apply the presenter to the data before sending it to the client. Presenters work with collections, single resources, and nested resources, allowing for data transformation at any response level.

Filament Starter Kit

The RESTPresenter package includes a Filament Starter Kit, providing a robust foundation for your Filament projects:

Need Something More Advanced?

We are developing a full Filament Kit with additional features for comprehensive CRUD generation in your Filament project. This advanced solution is intended for those who require more robust functionality and will be released under a sponsorship model. Once we reach our sponsorship milestones, the full Filament Kit will be open-sourced.

The full kit will save developers time by providing advanced solutions out of the box. However, the Starter Kit still allows for full CRUD implementation, though it may require more time and effort. If you’re interested in the advanced Filament Kit, reach out to us on Discord to express your interest and support its development through sponsorship.

Standalone Laravel Setup

RESTPresenter seamlessly integrates into any Laravel application, allowing you to generate API resources effortlessly from your selected models.

Initial Setup

Customize RESTPresenter for your project with our setup command:

php artisan rest-presenter:setup

We recommend installing the Sanctum starter kit, so this has been pre-selected for you. Note Filament now has a dedicated command to install the RESTPresenter plugin so has been removed from the setup command.

Generate Resources (Prompts)

To generate a new resource, use the following command:

php artisan rest-presenter:make-resource

This command will guide you through creating a new resource. Prompts will allow you to automatically generate presenters, filters, data, and set up your resource ready to use. All model relationships and fields are automatically detected throughout the prompt process. Additionally, we provide a custom option for most prompts to generate without auto-detection.

Configuration

We no longer publish the configuration by default. This is to provide better support for future updates and to prevent conflicts with your existing configuration. If you need to publish the configuration, you can do so with vendor:publish however we do not recommend this approach.

Instead we have made sure that you can override any configuration directly in your .env file. This allows you to customize the package to your needs without the need to publish the configuration.

Here is a list of all available configuration options including their default values:

# RESTPresenter Generator Configuration
REST_PRESENTER_GENERATOR_PATH=app/Api
REST_PRESENTER_GENERATOR_NAMESPACE=App\Api
REST_PRESENTER_GENERATOR_TS_TYPES_PATH=rest-presenter/types
REST_PRESENTER_GENERATOR_TS_TYPES_KEYWORD=interface
REST_PRESENTER_GENERATOR_TS_TYPES_TRAILING_SEMICOLON=true
REST_PRESENTER_GENERATOR_TEST_PATH=tests/Feature/Api/v1
REST_PRESENTER_GENERATOR_TEST_NAMESPACE=Tests\Feature\Api\v1

# RESTPresenter API Configuration
REST_PRESENTER_API_PREFIX=api
REST_PRESENTER_API_VERSION=v1
REST_PRESENTER_API_NAME=API
REST_PRESENTER_API_DEBUG=true
REST_PRESENTER_API_PRESENTER_HEADER=X-REST-PRESENTER

# RESTPresenter Auth Configuration
REST_PRESENTER_AUTH_API_KEY=rest-presenter-secret-key
REST_PRESENTER_AUTH_API_TOKEN_NAME=rest-presenter-api-token
REST_PRESENTER_AUTH_API_KEY_HEADER=X-REST-PRESENTER-API-KEY
REST_PRESENTER_AUTH_ENABLE_API_KEY=true
REST_PRESENTER_AUTH_REGISTER_DATA_NAME="required|string|max:255"
REST_PRESENTER_AUTH_REGISTER_DATA_EMAIL="required|string|email|max:255|unique:users,email"
REST_PRESENTER_AUTH_REGISTER_DATA_PASSWORD="required|string|min:8|max:255|confirmed"
REST_PRESENTER_AUTH_LOGIN_DATA_EMAIL="required|string|email|max:255"
REST_PRESENTER_AUTH_LOGIN_DATA_PASSWORD="required|string|min:8"
REST_PRESENTER_AUTH_LOGOUT_REVOKE_ALL_TOKENS=false
REST_PRESENTER_AUTH_RATE_LIMIT_MAX_ATTEMPTS=5

# RESTPresenter Export Configuration
REST_PRESENTER_EXPORT_PROVIDER=postman

# RESTPresenter Export Insomnia Configuration
REST_PRESENTER_EXPORT_INSOMNIA_WORKSPACE_NAME="${APP_NAME} (RESTPresenter)"
REST_PRESENTER_EXPORT_INSOMNIA_WORKSPACE_DESCRIPTION="${APP_NAME} RESTPresenter Workspace"
REST_PRESENTER_EXPORT_INSOMNIA_ENVIRONMENT_NAME="${APP_NAME} (RESTPresenter)"
REST_PRESENTER_EXPORT_INSOMNIA_ENVIRONMENT_BASE_URL="${APP_URL}"
REST_PRESENTER_EXPORT_INSOMNIA_ENVIRONMENT_VERSION=v1

# RESTPresenter Export Postman Configuration
REST_PRESENTER_EXPORT_POSTMAN_INFO_NAME="${APP_NAME} (RESTPresenter)"
REST_PRESENTER_EXPORT_POSTMAN_INFO_SCHEMA="https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
REST_PRESENTER_EXPORT_POSTMAN_AUTH_METHOD=bearer
REST_PRESENTER_EXPORT_POSTMAN_AUTH_TOKEN=YOUR_API_TOKEN

# RESTPresenter Resource Configuration
REST_PRESENTER_RESOURCES_USER_PROFILE=\XtendPackages\RESTPresenter\Resources\Users\Presenters\Profile
REST_PRESENTER_RESOURCES_USER_USER=\XtendPackages\RESTPresenter\Resources\Users\Presenters\User

# RESTPresenter Panel Configuration
REST_PRESENTER_PANEL_BRAND_NAME=RESTPresenter
REST_PRESENTER_PANEL_BRAND_LOGO=true
REST_PRESENTER_PANEL_PATH=rest-presenter
REST_PRESENTER_PANEL_MAX_WIDTH=7xl
REST_PRESENTER_PANEL_TOP_NAVIGATION=false

Changelog

Please see CHANGELOG this is automatically generated from commits which follow the conventional commits standards and updated with each release.

Contributing

Please see our CONTRIBUTING guide if you are thinking of contributing to this package.

License

RESTPresenter is open-source software licensed under the MIT License