Download the PHP package hyvor/helper-laravel without Composer

internal

This package provides the following features for HYVOR applications in Laravel:

• Authentication (with fake provider)
• HTTP helpers
• Internationalization
• Component API
• Billing API

Installation

Install via composer:

Include ./vendor/hyvor/internal/extension.neon in your PHPStan config:

Auth

This library connects with the HYVOR Auth API to authenticate users. It supports the following providers:

Configuration

The following environment variables are supported. See config.php for configuration options. Environment variables should be set in the .env file.

User Data

The AuthUser class is used to represent the user. It has the following properties:

• int $id - the user ID
• string $name - the user's name
• string $email - the user's email
• ?string $username - the user's username (only HYVOR)
• ?string $picture_url - the user's picture URL
• ?string $location - the user's location
• ?string $bio - the user's bio
• ?string $website_url - the user's website URL

Fetching Data

Use the following methods to fetch data by user ID, email, or username:

Auth check

To check if the user is logged in:

Redirects

Programmatic Redirects

Use the following methods to get redirects to login, signup, and logout pages:

By default, the user will be redirected to the current page after login or logout. You may also set the redirect parameter to redirect the user to a specific page after login or logout:

HTTP Redirects

The following routes are automatically added to the application for HTTP redirects:

• /api/auth/login
• /api/auth/signup
• /api/auth/logout

All endpoints support a redirect parameter to redirect the user to a specific page/URL after login or logout.

Testing

In testing, the provider is always set to fake. The FakeProvider always generate dummy data for all requested ids, emails, and usernames. This is useful for testing. You may also set a database of users for the FakeProvider to return specific data for specific users as follows:

• FakeProvider::databaseSet($database) - sets the database (collection) of users.
• FakeProvider::databaseAdd($user) - adds a user to the database.
• FakeProvider::databaseClear() - clears the database. This should be called after each test case (tearDown).

When a database is set, the FakeProvider will return the user data from that database only. This is useful for testing the following scenarios:

• When a user is not found (set an empty database).
• When a user's specific details are needed (e.g. name, email, etc.) as in the above example.

In most other cases, you should be able to use the Fake provider without setting a database. Because it automatically generates dummy data for all users, you do not need to seed a database before each test case. However, note that user's data will be different for each test case.

Billing

License and plan classes should be added to the internal library.

Create Subscription Intent

Create a new subscription intent with the latest plan version.

Get License

You would usually get the license to check if a user/resource has access to a certain feature.

This function gets the license in the following order:

• Custom resource license, if set
• Custom user license, if set
• Subscription license based on the plan, if set
• Trial license, if within the trial

If no license was found, null is returned.

Resources

When a user creates a resource in the component (ex: a blog in HB), it should call Resource::register() within a transaction to register that resource in the core. Core will start the trial for the user if that's the first resource of the user in that component.

Local Development

To ease local development, this package is configured to mock Auth and Billing services so that you can develop without running the core. This feature is enabled by the src/InternalFake.php file, which has the following methods:

If you need to customize the fake data,

• You can edit the InternalFake class.
• (recommended) You can add a src/InternalFakeExtended.php file and extend the InternalFake class. This file is git-ignored, so you can add your own customizations here without affecting the internal package.

HTTP

This library provides a few helpers for handling HTTP requests.

Exceptions

HttpException

Use Hyvor\Internal\Http\Exceptions\HttpException to throw an HTTP exception. This is, in most cases, this error will be sent to the client in the JSON response. Therefore, only use this in middleware and controllers (never in domains). Never share sensitive information in the message.

Middleware

Auth Middleware

Use Hyvor\Internal\Http\Middleware\AuthMiddleware to require authentication for a route.

If the user is not logged in, an HttpException is thrown with status code 401. If the user is logged in, an AccessAuthUser object (extends AuthUser) is added to the service container, which can be used as follows:

Routes

Here's a list of routes added by this library:

• POST /api/auth/check - returns the logged-in user or null.
• GET /api/auth/login - redirects to the login page.
• GET /api/auth/signup - redirects to the signup page.
• GET /api/auth/logout - redirects to the logout page.

Models

HasUser Trait

You may add the Hyvor\Internal\Auth\HasUser trait to any model to add a user() method to it. This method returns the AuthUser object, using the user_id column of the model.

Internationalization

This library provides some helpers to handle internationalization. Most of the time, strings are used in the front-end in HYVOR apps, but for some cases like emails, you may need to translate strings in the back-end. Similar to our Design System, we use the ICU message format. Therefore, you can share the same translations between the front-end and back-end.

All JSON translation files should be places in a directory, which is set in the config file. The default directory is resources/lang. The file name should be the language code (e.g. en-US.json). The file should be a JSON object with keys as the message IDs and values as the translations. Nested keys are also supported. The locales are loaded from the files in the directory.

Metrics

To enable metrics, add the middleware to global middleware in app/Http/Kernel.php:

The middleware will automatically do the following:

• Record prometheus metrics for each request.
• Serve the metrics at /api/metrics on local.
• Serve the metrics at /* if HYVOR_METRICS_SERVER environment variable is set to true.

The apcu extension is required to persist metrics between requests. This has been tested with FrankenPHP. It does not work with the CLI.

Usage

The locale is matched to the closest available locale. For example, if you have the following locales:

• en-US
• fr-FR
• es

You can also use the ClosestLocale class to get the closest locale to a given locale.

The I18n singleton class is the base class that manages the locales in the app.