Hybridly

Upgrade guide ​

This guide describes how to upgrade from v0.9.x to v0.10.x.

WARNING

Hybridly v0.10.x is still in beta, and breaking changes are still to be expected. It is not advised to upgrade right now.

Upgrade dependencies high impact ​

v0.10.x targets Laravel 13+ and Vite 8+.

Update imports high impact ​

Many classes have changed their namespace. Update your imports accordingly:

  • Hybridly\View\Factory is now Hybridly\HybridResponseFactory,
  • Hybridly\Support\Hybridable is now Hybridly\SerializesProperties.
  • All Hybridly\Support\Property classes are now in Hybridly\,
  • All Hybridly\Support\Configuration classes are now in Hybridly\Configuration\,

Update exception handling high impact ​

The HandleHybridExceptions class is no longer available to use in bootstrap/app.php. Instead, handle exceptions in a service provider:

php
use Hybridly\Hybridly;
use Symfony\Component\HttpFoundation\Response;
use function Hybridly\view;

final class AppServiceProvider extends ServiceProvider
{
    public function boot(Hybridly $hybridly): void
    {
        $hybridly->renderExceptionsUsing(fn (Response $response) => view('error', [
            'status' => $response->getStatusCode(),
        ]));
    }
}

Namespace changes high impact ​

  • Hybridly\Support\Hybridable -> Hybridly\Hybridable

Global middleware is now final high impact ​

Flash data is no longer shared by default high impact ​

Validation is now protocol-level high impact ​

Validation errors are no longer injected into view.properties.errors. They now live in the protocol payload root under validation, grouped by error bag.

Before:

json
{
	"view": {
		"properties": {
			"errors": {
				"email": "The email field is required."
			}
		}
	}
}

After:

json
{
	"validation": {
		"default": {
			"email": "The email field is required."
		}
	}
}

If you were reading validation errors from global properties, migrate to protocol/context access:

ts
import { useProperty } from 'hybridly/vue'
const errors = useProperty('errors')

import { useValidationBag } from 'hybridly/vue'
const errors = useValidationBag()

If you need full bag access:

ts
import { useValidation } from 'hybridly/vue'

const validation = useValidation()

useForm keeps working as before. errorBag support is still available, and bags are now merged at the protocol level so multiple forms can coexist without colliding.

Replace partial with on_demand high impact ​

The partial function was renamed to on_demand. Even if you grew used to it, the name was definitely confusing.

php
use function Hybridly\partial;
use function Hybridly\on_demand;

return hybridly('users.index', [
    'filters' => partial(fn () => $filters),
    'filters' => on_demand(fn () => $filters),
]);

Architecture API changes high impact ​

The ComponentsResolver interface was simplified:

  • loadModulesFrom was removed.
  • loadComponentsFrom was removed.
  • loadTypeScriptFilesFrom was removed.
  • loadModuleFrom now accepts only directory and namespace.
php
$hybridly->loadModuleFrom(
    directory: __DIR__,
    namespace: 'billing',
    deep: true,
    loadViews: true,
    loadLayouts: true,
    loadComponents: true,
    loadTypeScript: true,
);

If you need fine-grained registration, use:

  • loadViewsFrom
  • loadLayoutsFrom
  • addView
  • addLayout

Update refining filters high impact ​

The generic Filters\Filter class has been replaced by explicit filter classes.

php
use Hybridly\Refining\Filters;

Filters\Filter::make('name');
Filters\TextFilter::make('name');
Filters\NumericFilter::make('price');
Filters\DateFilter::make('published_at');

If you implemented custom filters, note that Filter::apply now receives a QueryFilter value object:

Before:

php
public function apply(Builder $builder, mixed $value, string $property): void
{
    // ...
}

After:

php
use Hybridly\Refining\Filters\QueryFilter;

public function apply(Builder $builder, QueryFilter $filter, string $property): void
{
    $value = $filter->value;
    // ...
}

Updating tsconfig.json medium impact ​

The tsconfig.json auto-generated in .hybridly now expects the root tsconfig.json to be the following:

json
{
	"files": [],
	"references": [
		{ "path": "./.hybridly/tsconfig.json" },
		{ "path": "./.hybridly/tsconfig.node.json" }
	]
}