### Aspect Oriented Programming (AOP)
Aspect-Oriented Programming (AOP) is a pattern that realizes flexible applications by separating essential concerns such as business logic from cross-cutting concerns such as logging and caching. Cross-cutting concerns refer to functions or processes that span across multiple modules or layers. It is possible to bind cross-cutting processes based on search conditions and flexibly configure them based on context.
BEAR.Sunday's AOP uses a separate package called Ray.Aop, which declaratively binds cross-cutting processes by attaching PHP attributes to classes and methods. Ray.Aop conforms to Java's [AOP Alliance](https://aopalliance.sourceforge.net/).
AOP is often misunderstood as a technology that "has the strong power to break the existing order". However, its raison d'être is not to exercise power beyond constraints but to complement areas where object-orientation is not well-suited, such as exploratory assignment of functions using matchers and separation of cross-cutting processes. AOP is a paradigm that can create cross-cutting constraints for applications, in other words, it functions as an application framework.
## Performance and Scalability
### ROA-based Event-Driven Content Strategy with Modern CDN Integration
BEAR.Sunday realizes an advanced event-driven caching strategy by integrating with instant purge-capable CDNs such as Fastly, with Resource Oriented Architecture (ROA) at its core. Instead of invalidating caches based on the conventional TTL (Time to Live), this strategy immediately invalidates the CDN and server-side caches, as well as ETags (entity tags), in response to resource state change events.
By taking this approach of creating non-volatile and persistent content on CDNs, it not only avoids SPOF (Single Point of Failure) and achieves high availability and fault tolerance but also maximizes user experience and cost efficiency. It realizes the same distributed caching as static content for dynamic content, which is the original principle of the Web. It re-realizes the scalable and network cost-reducing distributed caching principle that the Web has had since the 1990s with modern technology.
#### Cache Invalidation by Semantic Methods and Dependencies
In BEAR.Sunday's ROA, each resource operation is given a semantic role. For example, the GET method retrieves a resource, and the PUT method updates a resource. These methods collaborate in an event-driven manner and efficiently invalidate related caches. For instance, when a specific resource is updated, the cache of resources that require that resource is invalidated. This ensures data consistency and freshness, providing users with the latest information.
#### Identity Confirmation and Fast Response with ETag
By setting ETags before the system boots, content identity can be quickly confirmed, and if there are no changes, a 304 Not Modified response is returned to minimize network load.
#### Partial Updates with Donut Caching and ESI
BEAR.Sunday adopts a donut caching strategy and uses ESI (Edge Side Includes) to enable partial content updates at the CDN edge. This technology allows for dynamic updates of only the necessary parts without re-caching the entire page, improving caching efficiency.
In this way, BEAR.Sunday and Fastly's integration of ROA-based caching strategy not only realizes advanced distributed caching but also enhances application performance and fault tolerance.
### Runtime Optimization
BEAR.Sunday is designed to minimize framework overhead regardless of server configuration.
DI resolution is completed at compile time, with no container lookups at runtime. The entire application is generated as a single root object variable and reused across requests. In php-fpm configurations, the pre-compiled dependency graph and opcache enable fast bootstrapping.
In Swoole configurations, persistent workers reduce bootstrapping to a single initial boot. Coroutine-context-based request isolation enables safe concurrent processing without reliance on superglobals. Combined with the transparent parallel execution described next, I/O wait time is further minimized.
### Transparent Parallel Execution
In BEAR.Sunday, a URI expresses "intent" rather than being merely a communication protocol or locator. `app://self/user` expresses only the intent "I want user information"—whether it comes from MySQL or Redis is hidden from the application.
This complete separation of "What" from "How" enables multiple resources embedded with `#[Embed]` to be fetched in parallel without changing any application code. Resource classes written 10 years ago can benefit from parallel execution just by adding a Module.
Three tiers of solutions are available based on server environment constraints: ext-parallel (thread pool), Swoole (coroutines), and mysqli (DB queries only). Whichever you choose, application code requires no changes. Develop and debug with standard PHP, then switch to parallel execution in production with just a configuration change.
## Developer Experience
### Ease of Testing
BEAR.Sunday allows for easy and effective testing due to the following design features:
* Each resource is independent, and testing is easy due to the stateless nature of REST requests.
Since the state and representation of resources are clearly separated, it is possible to test the state of resources even when they are in HTML representation.
* API testing can be performed while following hypermedia links, and tests can be written in the same code for PHP and HTTP.
* Different implementations are bound during testing through context-based binding.
### Application as Documentation
In BEAR.Sunday, the application itself is the documentation. Multiple documentation formats are automatically generated from code.
- **ApiDoc HTML**: Developer reference
- **OpenAPI 3.1**: Toolchain integration
- **JSON Schema**: Information model definition
- **llms.txt**: AI-readable application overview
When using an ALPS profile as the SSOT (Single Source of Truth), you define the application semantics (vocabulary, state transitions, operation meanings) first, then generate code from it. The same document holds different meanings for different readers—developers see endpoints, architects read state transitions, and AI extracts ontology.
### Visualization and Debugging
Utilizing the technical feature of resources rendering themselves, during development, the scope of resources can be indicated on HTML, resource states can be monitored, and PHP code and HTML templates can be edited in an online editor and reflected in real-time.
## Extensibility and Integration
### Integration of PHP Interfaces and SQL Execution
In BEAR.Sunday, the execution of SQL statements for interacting with databases can be easily managed through PHP interfaces. It is possible to directly bind SQL execution objects to PHP interfaces without implementing classes. The boundary between the domain and infrastructure is connected by PHP interfaces.
In that case, types can also be specified for arguments, and any missing parts are dependency-resolved by DI and used as strings. Even when the current time is needed for SQL execution, there is no need to pass it; it is automatically bound. This helps keep the code concise as the client is not responsible for passing all arguments.
Moreover, direct management of SQL makes debugging easier when errors occur. The behavior of SQL queries can be directly observed, allowing for quick identification and correction of problems.
### Integration with Other Systems
BEAR.Sunday resources can be accessed through various interfaces. In addition to web interfaces, resources can be accessed directly from the console, allowing the same resources to be used from both web and command-line interfaces without changing the source code. Furthermore, using BEAR.CLI, resources can be distributed as standalone UNIX commands. Multiple BEAR.Sunday applications can also run concurrently within the same PHP runtime, enabling collaboration between independent applications without building microservices.
### Stream Output
By assigning streams such as file pointers to the body of a resource, large-scale content that cannot be handled in memory can be output. In that case, streams can also be mixed with ordinary variables, allowing flexible output of large-scale responses.
### Gradual Migration from Other Systems
BEAR.Sunday provides a gradual migration path and enables seamless integration with other frameworks and systems such as Laravel and Symfony. This framework can be implemented as a Composer package, allowing developers to gradually introduce BEAR.Sunday's features into their existing codebase.
### Flexibility in Technology Migration
BEAR.Sunday protects investments in preparation for future technological changes and evolving requirements. Even if there is a need to migrate from this framework to another framework or language, the constructed resources will not go to waste. In a PHP environment, BEAR.Sunday applications can be integrated as Composer packages and continuously utilized, and BEAR.Thrift allows efficient access to BEAR.Sunday resources from other languages. When not using Thrift, access via HTTP is also possible. SQL code can also be easily reused.
Even if the library being used is strongly dependent on a specific PHP version, different versions of PHP can coexist using BEAR.Thrift.
## Design Philosophy and Quality
### Adoption of Standard Technologies and Elimination of Proprietary Standards
BEAR.Sunday has a design philosophy of adopting standard technologies as much as possible and eliminating framework-specific standards and rules. For example, it supports content negotiation for JSON format and www-form format HTTP requests by default and uses the [vnd.error+json](https://github.com/blongden/vnd.error) media type format for error responses. It actively incorporates standard technologies and specifications such as adopting [HAL](https://datatracker.ietf.org/doc/html/draft-kelly-json-hal) (Hypertext Application Language) for links between resources and using [JsonSchema](https://json-schema.org/) for validation.
On the other hand, it eliminates proprietary validation rules and framework-specific standards and rules as much as possible.
### Object-Oriented Principles
BEAR.Sunday emphasizes object-oriented principles to make applications maintainable in the long term.
#### Composition over Inheritance
Composition is recommended over inheritance classes. Generally, directly calling a parent class's method from a child class can potentially increase the coupling between classes. The only abstract class that requires inheritance at runtime by design is the resource class `BEAR\Resource\ResourceObject`, but the methods of ResourceObject exist solely for other classes to use. There is no case in BEAR.Sunday where a user calls a method of a framework's parent class that they have inherited at runtime.
#### Everything is Injected
Framework classes do not refer to "configuration files" or "debug constants" during execution to determine their behavior. Dependencies corresponding to the behavior are injected. This means that to change the application's behavior, there is no need to change the code; only the binding of the implementation of the dependency to the interface needs to be changed. Constants like APP_DEBUG or APP_MODE do not exist. There is no way to know in what mode the software is currently running after it has started, and there is no need to know.
### Permanent Assurance of Backward Compatibility
BEAR.Sunday is designed with an emphasis on maintaining backward compatibility in the evolution of software and has continued to evolve without breaking backward compatibility since its release. In modern software development, frequent breaking of backward compatibility and the associated burden of modification and testing have become a challenge, but BEAR.Sunday has avoided this problem.
BEAR.Sunday not only adopts semantic versioning but also does not perform major version upgrades that involve breaking changes. It prevents new feature additions or changes to existing features from affecting existing code. Code that has become old and unused is given the attribute "deprecated" but is never deleted and does not affect the behavior of existing code. Instead, new features are added, and evolution continues.
### Acyclic Dependencies Principle (ADP)
The Acyclic Dependencies Principle states that dependencies should be unidirectional and non-circular. The BEAR.Sunday framework adheres to this principle and is composed of a series of packages with a hierarchical structure where larger framework packages depend on smaller framework packages. Each level does not need to be aware of the existence of other levels that encompass it, and the dependencies are unidirectional and do not form cycles. For example, Ray.Aop is not even aware of the existence of Ray.Di, and Ray.Di is not aware of the existence of BEAR.Sunday.
As backward compatibility is maintained, each package can be updated independently. Moreover, there is no version number that locks the entire system, as seen in other frameworks, and there is no mechanism for object proxies that hold cross-cutting dependencies between objects.
The Acyclic Dependencies Principle is in harmony with the DI (Dependency Injection) principle, and the root object generated during the bootstrapping process of BEAR.Sunday is also constructed following the structure of this Acyclic Dependencies Principle.
[
](/images/screen/clean-architecture.png)
The same applies to the runtime. When accessing a resource, first, the cross-cutting processing of the AOP aspects bound to the method is executed, and then the method determines the state of the resource. At this point, the method is not aware of the existence of the aspects bound to it. The same goes for resources embedded in the resource's state. They do not have knowledge of the outer layers or elements. The separation of concerns is clearly defined.
### Code Quality
To provide applications with high code quality, the BEAR.Sunday framework also strives to maintain a high standard of code quality.
* The framework code is applied at the strictest level by both static analysis tools, Psalm and PHPStan.
* It maintains 100% test coverage and nearly 100% type coverage.
* It is fundamentally an immutable system and is so clean that initialization is not required every time, even in tests. It unleashes the power of PHP's asynchronous communication engines like Swoole.
### Architecture-Enabled Security Analysis
BEAR.Sunday's architecture fundamentally simplifies security analysis.
Every endpoint is a ResourceObject with explicit `onGet` and `onPost` methods, inputs are declared via JSON Schema, and dependencies are explicit through constructor injection. With no hidden magic or global state, static analysis tools can trace complete data flows.
This declarative architecture enables multi-layered security scanning combining SAST (static analysis), DAST (dynamic testing), taint analysis, and AI auditing. Framework-aware specialized tools detect vulnerabilities that generic tools cannot find.
## The Value BEAR.Sunday Brings
### Value for Developers
* Improved productivity: Based on robust design patterns and principles with constraints that don't change over time, developers can focus on core business logic.
* Collaboration in teams: By providing development teams with consistent guidelines and structure, it keeps the code of different engineers loosely coupled and unified, improving code readability and maintainability.
* Flexibility and extensibility: BEAR.Sunday's policy of not including libraries brings developers flexibility and freedom in component selection.
* Ease of testing: BEAR.Sunday's DI (Dependency Injection) and ROA (Resource Oriented Architecture) increase the ease of testing.
### Value for Users
* High performance: BEAR.Sunday's runtime optimization and CDN-centric caching strategy brings users a fast and responsive experience.
* Reliability and availability: BEAR.Sunday's CDN-centric caching strategy minimizes single points of failure (SPOF), allowing users to enjoy stable services.
* Ease of use: BEAR.Sunday's excellent connectivity makes it easy to collaborate with other languages and systems.
### Value for Business
* Reduced development costs: The consistent guidelines and structure provided by BEAR.Sunday promote a sustainable and efficient development process, reducing development costs.
* Reduced maintenance costs: BEAR.Sunday's approach to maintaining backward compatibility increases technical continuity and minimizes the time and cost of change response.
* High extensibility: With technologies like DI (Dependency Injection) and AOP (Aspect Oriented Programming) that change behavior while minimizing code changes, BEAR.Sunday allows applications to be easily extended in line with business growth and changes.
* Excellent User Experience (UX): BEAR.Sunday provides high performance and high availability, increasing user satisfaction, enhancing customer loyalty, expanding the customer base, and contributing to business success.
### Summary
Excellent constraints do not change. The constraints brought by BEAR.Sunday provide specific value to developers, users, and businesses respectively.
BEAR.Sunday is a framework designed based on the principles and spirit of the Web, providing developers with clear constraints to empower them to build flexible and robust applications.
# Version
## Supported PHP
[](https://github.com/bearsunday/BEAR.SupportedVersions/actions/workflows/continuous-integration.yml)
BEAR.Sunday supports the following supported PHP versions
* `8.1` (Old stable 25 Nov 2021 - 31 Dec 2025)
* `8.2` (Old stable 8 Dec 2022 - 31 Dec 2026)
* `8.3` (Old stable 23 Nov 2023 - 31 Dec 2027)
* `8.4` (Current stable 21 Nov 2024 - 31 Dec 2028)
* End of life ([EOL](http://php.net/eol.php))
* `5.5` (21 Jul 2016)
* `5.6` (31 Dec 2018)
* `7.0` (3 Dec 2018)
* `7.1` (1 Dec 2019)
* `7.2` (30 Nov 2020)
* `7.3` (6 Dec 2021)
* `7.4` (28 Nov 2022)
* `8.0` (26 Nov 2023)
The new optional package will be developed based on the current stable PHP. We encourage you to use the current stable PHP for quality, performance and security.
[BEAR.SupportedVersions](https://github.com/bearsunday/BEAR.SupportedVersions/), you can check the tests for each version in CI.
## Semver
BEAR.Sunday follows [Semantic Versioning](http://semver.org/lang/en/). It is not necessary to modify the application code on minor version upgrades.
`composer update` can be done at any time for packages.
## Version Policy
* The core package of the framework does not make a breaking change which requires change of user code.
* Since it does not do destructive change, it handles unnecessary old ones as `deprecated` but does not delete and new functions are always "added".
* When PHP comes to an EOL and upgraded to a major version (ex. `5.6` →` 7.0`), BEAR.Sunday will not break the BC of the application code. Even though the version number of PHP that is necessary to use the new module becomes higher, changes to the application codes are not needed.
BEAR.Sunday emphasizes clean code and **longevity**.
## Package version
The version of the framework does not lock the version of the library. The library can be updated regardless of the version of the framework.
# Quick Start
Installation is done via [composer](http://getcomposer.org)
```bash
VENDOR=MyVendor PACKAGE=MyProject composer create-project bear/skeleton my-project
cd my-project
```
Use `VENDOR` to specify the vendor name and `PACKAGE` to specify the package name for installation. If not specified, you will be prompted interactively.
Next, let's create a new resource. A resource is a class which corresponds, for instance, to a JSON payload (if working with an API-first driven model)
or a web page.
Create your own basic page resource in `src/Resource/Page/Hello.php`
```php
body = [
'greeting' => 'Hello ' . $name
];
return $this;
}
}
```
In the above example, when the page is requested using a GET method, `Hello` and the `$name` parameter (which corresponds to `$_GET['name']`) are joined, and assigned to a variable `greeting`.
The BEAR.Sunday application that you have created will work on a web server, but also in the console.
```bash
php bin/page.php get /hello
php bin/page.php get '/hello?name=World'
```
```bash
200 OK
Content-Type: application/hal+json
{
"greeting": "Hello World",
"_links": {
"self": {
"href": "/hello?name=World"
}
}
}
```
Let us fire up the php server and access our page at [http://127.0.0.1:8080/hello](http://127.0.0.1:8080/hello).
```bash
php -S 127.0.0.1:8080 -t public
```
```bash
curl -i 127.0.0.1:8080/hello
```
## Core Concepts
# Package
BEAR.Sunday application is a composer package taking BEAR.Sunday framework as dependency package.
You can also install another BEAR.Sunday application package as dependency.
## Application organization
The file layout of the BEAR.Sunday application conforms to [php-pds/skeleton](https://github.com/php-pds/skeleton) standard.
### Invoke sequence
1. Console input (`bin/app.php`, `bin/page.php`) or the web entry file (`public/index.php`) executes the `bootstrap.php` function.
2. The `$app` application object is created for the given `$context` in `bootstrap.php`.
3. The router in `$app` converts the external resource request to an internal resource request.
4. The resource request is invoked, and the resulting representation is transferred to the client.
### bootstrap/
You can access same resource through console input or web access with same boot file.
```bash
php bin/app.php options /todos // console API access (app resource)
```
```bash
php bin/page.php get '/todos?id=1' // console Web access (page resource)
```
```bash
php -S 127.0.0.1bin/app.php // PHP server
```
You can create your own boot file for different context.
### bin/
Place command-line executable files.
### src/
Place application class file.
### public/
Web public folder.
### var/
`log` and `tmp` need write permission. By default they are `var/tmp/{context}` and `var/log/{context}`.
To place them outside the project tree, pass paths to the `Meta` constructor ([Production](production.html#writable-paths)).
## Framework Package
### ray/aop
[](https://scrutinizer-ci.com/g/ray-di/Ray.Aop/)
[](https://codecov.io/gh/ray-di/Ray.Aop)
[](https://shepherd.dev/github/ray-di/Ray.Aop)
[](https://github.com/ray-di/Ray.Aop/actions/workflows/continuous-integration.yml)
An aspect oriented framework based on Java AOP Alliance API.
### ray/di
[](https://scrutinizer-ci.com/g/ray-di/Ray.Di/)
[](https://codecov.io/gh/ray-di/Ray.Di)
[](https://shepherd.dev/github/ray-di/Ray.Di)
[](https://github.com/ray-di/Ray.Di/actions/workflows/continuous-integration.yml)
A Google Guice style DI framework. It contains `ray/aop`.
### bear/resource
[](https://scrutinizer-ci.com/g/bearsunday/BEAR.Resource/?branch=1.x)
[](https://codecov.io/gh/bearsunday/BEAR.Resource)
[](https://shepherd.dev/github/bearsunday/BEAR.Resource)
[](https://github.com/bearsunday/BEAR.Resource/actions/workflows/continuous-integration.yml)
A REST framework for PHP object as a service. It contains `ray/di`.
### bear/sunday
[](https://scrutinizer-ci.com/g/bearsunday/BEAR.Sunday/?branch=1.x)
[](https://codecov.io/gh/bearsunday/BEAR.Sunday)
[](https://shepherd.dev/github/bearsunday/BEAR.Sunday)
[](https://github.com/bearsunday/BEAR.Sunday/actions/workflows/continuous-integration.yml)
A web application interface package. It contains `bear/resource`.
### bear/package
[](https://scrutinizer-ci.com/g/bearsunday/BEAR.Package/?branch=1.x)
[](https://codecov.io/gh/bearsunday/BEAR.Pacakge)
[](https://shepherd.dev/github/bearsunday/BEAR.Package)
[](https://github.com/bearsunday/BEAR.Package/actions/workflows/continuous-integration.yml)
A web application implmentation package. It contains `bear/sunday`.
## Library Package
Optional library package can be installed with `composer require` command.
| **Category** | **Composer package** | **Library**
| Router |
| |[bear/aura-router-module](https://github.com/bearsunday/BEAR.AuraRouterModule) | [Aura.Router v2](https://github.com/auraphp/Aura.Router/tree/2.x) |
| Database |
|| [ray/media-query](https://github.com/ray-di/Ray.MediaQuery) |
|| [ray/aura-sql-module](https://github.com/ray-di/Ray.AuraSqlModule) | [Aura.Sql v2](https://github.com/auraphp/Aura.Sql/tree/2.x)
|| [ray/dbal-module](https://github.com/ray-di/Ray.DbalModule) | [Doctrine DBAL](https://github.com/doctrine/dbal)
|| [ray/cake-database-module](https://github.com/ray-di/Ray.CakeDbModule) | [CakePHP v3 database](https://github.com/cakephp/database)
|| [ray/doctrine-orm-module](https://github.com/kawanamiyuu/Ray.DoctrineOrmModule) | [Doctrine ORM](https://github.com/doctrine/doctrine2)
| Storage |
||[bear/query-repository](https://github.com/bearsunday/BEAR.QueryRepository) | CQRS inspired repository
||[bear/query-module](https://github.com/ray-di/Ray.QueryModule) | Separation of external access such as DB or Web API
| Web
| |[madapaja/twig-module](http://bearsunday.github.io/manuals/1.0/ja/html.html) | [Twig](http://twig.sensiolabs.org/)
| |[ray/web-form-module](http://bearsunday.github.io/manuals/1.0/ja/form.html) | Web form
| |[ray/aura-web-module](https://github.com/Ray-Di/Ray.AuraWebModule) | [Aura.Web](https://github.com/auraphp/Aura.Web)
| |[ray/aura-session-module](https://github.com/ray-di/Ray.AuraSessionModule) | [Aura.Session](https://github.com/auraphp/Aura.Session)
| |[ray/symfony-session-module](https://github.com/kawanamiyuu/Ray.SymfonySessionModule) | [Symfony Session](https://github.com/symfony/http-foundation/tree/master/Session)
| Validation |
| |[ray/validate-module](https://github.com/ray-di/Ray.ValidateModule) | [Aura.Filter](https://github.com/auraphp/Aura.Filter)
| |[satomif/extra-aura-filter-module](https://github.com/satomif/ExtraAuraFilterModule)| [Aura.Filter](https://github.com/auraphp/Aura.Filter)
| Authorization and Authentication
| |[ray/oauth-module](https://github.com/Ray-Di/Ray.OAuthModule) | OAuth
| |[kuma-guy/jwt-auth-module](https://github.com/kuma-guy/BEAR.JwtAuthModule) | JSON Web Token
| |[ray/role-module](https://github.com/ray-di/Ray.RoleModule) | Zend Acl
| |[bear/acl-resource](https://github.com/bearsunday/BEAR.AclResource) | ACL based embedded resource
| Hypermedia
| |[kuma-guy/siren-module](https://github.com/kuma-guy/BEAR.SirenModule) | Siren
| Development
| |[ray/test-double](https://github.com/ray-di/Ray.TestDouble) | Test Double
| Asynchronous high performance |
| |[MyVendor.Swoole](https://github.com/bearsunday/MyVendor.Swoole) | [Swoole](https://github.com/swoole/swoole-src)
## Vendor Package
You can reuse common packages and tool combinations as modules with only modules and share modules of similar projects.[^1]
## Semver
All packages adhere to [Semantic Versioning](http://semver.org/).
---
[^1]: See [Koriym.DbAppPackage](https://github.com/koriym/Koriym.DbAppPackage)
# 
## Boot File
To run an application, we need just two lines of code.
An entry point for a web server or console application access is usually set to `public/index.php` or `bin/app.php`.
As you can see below, we need to pass an application context to `bootstrap.php` the application script.
```php
install(new AuraSqlModule('mysql:host=localhost;dbname=test', 'username', 'password');
$this->install(new TwigModule));
// install basic module
$this->install(new PackageModule));
}
}
```
## DI bindings
`Ray.Di` is the core DI framework used in BEAR.Sunday. It binds interfaces to a class or factory to create an object graph.
```php?start_inline
// Class binding
$this->bind($interface)->to($class);
// Provider (factory) binding
$this->bind($interface)->toProvider($provider);
// Instance binding
$this->bind($interface)->toInstance($instance);
// Named binding
$this->bind($interface)->annotatedWith($annotation)->to($class);
// Singleton
$this->bind($interface)->to($class)->in(Scope::SINGLETON);
// Constructor binding
$this->bind($interface)->toConstructor($class, $named);
```
More info can be found at Ray.Di [README](https://github.com/ray-di/Ray.Di/blob/2.x/README.md)
### Binding Priority
See also: [Ray.Di Bindings](https://ray-di.github.io/manuals/1.0/en/bindings.html)
#### Within a Single Module
Bindings declared first take priority. In the following example, `Foo1` takes priority:
```php?start_inline
$this->bind(FooInterface::class)->to(Foo1::class);
$this->bind(FooInterface::class)->to(Foo2::class);
```
#### Module Installation Priority
Modules installed first take priority. In the following example, `Foo1Module` takes priority:
```php?start_inline
$this->install(new Foo1Module);
$this->install(new Foo2Module);
```
To give a later module priority, use `override()`. In the following example, `Foo2Module` takes priority:
```php?start_inline
$this->install(new Foo1Module);
$this->override(new Foo2Module);
```
#### Context String Priority
Context modules are processed in **reverse order** (right-to-left). For example, with context `prod-hal-api-app`:
```text
Installation order: AppModule → ApiModule → HalModule → ProdModule
```
Later installed modules can override earlier bindings. This means:
- `HalModule` takes priority over `AppModule`
- `ProdModule` takes priority over `HalModule`
When creating a custom context module that needs to override bindings from a built-in context (like `HalModule`), position it to the left of that context in the context string. For example, to override `HalModule`'s `RenderInterface` binding:
```php?start_inline
// Context: "prod-mycontext-hal-api-app"
// Installation order: AppModule → ApiModule → HalModule → MycontextModule → ProdModule
```
## AOP Bindings
We can "search" for classes and methods with a built-in `Matcher`, then interceptors can be bound to any found methods.
```php?start_inline
$this->bindInterceptor(
// In any class
$this->matcher->any(),
// Method(s) names that start with "delete"
$this->matcher->startWith('delete'),
// Bind a Logger interceptor
[LoggerInterceptor::class]
);
$this->bindInterceptor(
// The AdminPage class or a class inherited from it.
$this->matcher->SubclassesOf(AdminPage::class),
// Annotated with the @Auth annotation
$this->matcher->annotatedWith(Auth::class),
// Bind the AdminAuthenticationInterceptor
[AdminAuthenticationInterceptor::class]
);
```
`Matcher` has various binding methods.
* [Matcher::any](https://github.com/ray-di/Ray.Aop/blob/develop-2/src/MatcherInterface.php#L16) - Any
* [Matcher::annotatedWith](https://github.com/ray-di/Ray.Aop/blob/develop-2/src/MatcherInterface.php#L23) - Annotation
* [Matcher::subclassesOf](https://github.com/ray-di/Ray.Aop/blob/2.x/src/MatcherInterface.php#L30) - Sub class
* [Matcher::startsWith](https://github.com/ray-di/Ray.Aop/blob/2.x/src/MatcherInterface.php#L37) - start with name (class or method)
* [Matcher::logicalOr](https://github.com/ray-di/Ray.Aop/blob/2.x/src/MatcherInterface.php#L44) - OR
* [Matcher::logicalAnd](https://github.com/ray-di/Ray.Aop/blob/2.x/src/MatcherInterface.php#L51) - AND
* [Matcher::logicalNot](https://github.com/ray-di/Ray.Aop/blob/2.x/src/MatcherInterface.php#L58) - NOT
## Interceptor
In an interceptor a `MethodInvocation` object gets passed to the `invoke` method. We can the decorate the targetted instances so that you run computations before or after any methods on the target are invoked.
```php?start_inline
class MyInterceptor implements MethodInterceptor
{
public function invoke(MethodInvocation $invocation)
{
// Before invocation
// ...
// Method invocation
$result = $invocation->proceed();
// After invocation
// ...
return $result;
}
}
```
With the `MethodInvocation` object, you can access the target method's invocation object, method's and parameters.
* [MethodInvocation::proceed](https://github.com/ray-di/Ray.Aop/blob/develop-2/src/Joinpoint.php#L39) - Invoke method
* [MethodInvocation::getMethod](https://github.com/ray-di/Ray.Aop/blob/develop-2/src/MethodInvocation.php) - Get method reflection
* [MethodInvocation::getThis](https://github.com/ray-di/Ray.Aop/blob/develop-2/src/Joinpoint.php#L48) - Get object
* [MethodInvocation::getArguments](https://github.com/ray-di/Ray.Aop/blob/develop-2/src/Invocation.php) - Get parameters
Annotations can be obtained using the reflection API.
```php?start_inline
$method = $invocation->getMethod();
$class = $invocation->getMethod()->getDeclaringClass();
```
* `$method->getAnnotations()`
* `$method->getAnnotation($name)`
* `$class->getAnnotations()`
* `$class->getAnnotation($name)`
## Environment Settings
BEAR.Sunday does not have any special environment mode except `prod`.
A Module and the application itself are unaware of the current environment.
There is no way to get the current "mode", this is intentional to keep the code clean.
# DI
Dependency injection is basically providing the objects that an object needs (its dependencies) instead of having it construct them itself.
With dependency injection, objects accept dependencies in their constructors. To construct an object, you first build its dependencies. But to build each dependency, you need its dependencies, and so on. So when you build an object, you really need to build an object graph.
Building object graphs by hand is labour intensive, error prone, and makes testing difficult. Instead, **Dependency Injector** ([Ray.Di](https://github.com/ray-di/Ray.Di)) can build the object graph for you.
| What is object graph ?
| Object-oriented applications contain complex webs of interrelated objects. Objects are linked to each other by one object either owning or containing another object or holding a reference to another object. This web of objects is called an object graph and it is the more abstract structure that can be used in discussing an application's state. - [Wikipedia](http://en.wikipedia.org/wiki/Object_graph)
Ray.Di is the core DI framework used in BEAR.Sunday, which is heavily inspired by Google [Guice](http://code.google.com/p/google-guice/wiki/Motivation?tm=6) DI framework.See more detail at [Ray.Di Manual](https://ray-di.github.io/manuals/1.0/en/index.html).
# AOP
BEAR.Sunday **AOP** enables you to write code that is executed each time a matching method is invoked. It's suited for cross cutting concerns ("aspects"), such as transactions, security and logging. Because interceptors divide a problem into aspects rather than objects, their use is called Aspect Oriented Programming (AOP).
The method interceptor API implemented is a part of a public specification called [AOP Alliance](http://aopalliance.sourceforge.net/).
## Interceptor
[MethodInterceptors](https://github.com/ray-di/Ray.Aop/blob/2.x/src/MethodInterceptor.php) are executed whenever a matching method is invoked.
They have the opportunity to inspect the call: the method, its arguments, and the receiving instance.
They can perform their cross-cutting logic and then delegate to the underlying method.
Finally, they may inspect the return value or the exception and return. Since interceptors may be applied to many methods and will receive many calls, their implementation should be efficient and unintrusive.
```php
use Ray\Aop\MethodInterceptor;
use Ray\Aop\MethodInvocation;
class MyInterceptor implements MethodInterceptor
{
public function invoke(MethodInvocation $invocation)
{
// Process before method invocation
// ...
// Original method invocation
$result = $invocation->proceed();
// Process after method invocation
// ...
return $result;
}
}
```
## Bindings
"Find" the target class and method with `Matcher` and bind the interceptor to the matching method in [Module](module.html).
```php
$this->bindInterceptor(
$this->matcher->any(), // In any class,
$this->matcher->startsWith('delete'), // Method(s) names that start with "delete",
[Logger::class] // Bind a Logger interceptor
);
$this->bindInterceptor(
$this->matcher->subclassesOf(AdminPage::class), // Of the AdminPage class or a class inherited from it
$this->matcher->annotatedWith(Auth::class), // Annotated method with the @Auth annotation
[AdminAuthentication::class] //Bind the AdminAuthenticationInterceptor
);
```
There are various matchers.
* [Matcher::any](https://github.com/ray-di/Ray.Aop/blob/develop-2/src/MatcherInterface.php#L16)
* [Matcher::annotatedWith](https://github.com/ray-di/Ray.Aop/blob/develop-2/src/MatcherInterface.php#L23)
* [Matcher::subclassesOf](https://github.com/ray-di/Ray.Aop/blob/develop-2/src/MatcherInterface.php#L30)
* [Matcher::startsWith](https://github.com/ray-di/Ray.Aop/blob/develop-2/src/MatcherInterface.php#L37)
* [Matcher::logicalOr](https://github.com/ray-di/Ray.Aop/blob/develop-2/src/MatcherInterface.php#L44)
* [Matcher::logicalAnd](https://github.com/ray-di/Ray.Aop/blob/develop-2/src/MatcherInterface.php#L51)
* [Matcher::logicalNot](https://github.com/ray-di/Ray.Aop/blob/develop-2/src/MatcherInterface.php#L58)
```
With the `MethodInvocation` object, you can access the target method's invocation object, method's and parameters.
* [MethodInvocation::proceed](https://github.com/ray-di/Ray.Aop/blob/develop-2/src/Joinpoint.php#L39) - Invoke method
* [MethodInvocation::getMethod](https://github.com/ray-di/Ray.Aop/blob/develop-2/src/MethodInvocation.php) - Get method reflection
* [MethodInvocation::getThis](https://github.com/ray-di/Ray.Aop/blob/develop-2/src/Joinpoint.php#L48) - Get object
* [MethodInvocation::getArguments](https://github.com/ray-di/Ray.Aop/blob/develop-2/src/Invocation.php) - Pet parameters
Annotations can be obtained using the reflection API.
```php
$method = $invocation->getMethod();
$class = $invocation->getMethod()->getDeclaringClass();
```
* `$method->getAnnotations()` // get method annotations
* `$method->getAnnotation($name)`
* `$class->getAnnotations()` // get class annotations
* `$class->getAnnotation($name)`
## Own matcher
You can have your own matcher.
To create `contains` matcher, You need to provide a class which has two methods. One is `matchesClass` for a class match.
The other one is `matchesMethod` method match. Both return the boolean result of match.
```php
use Ray\Aop\AbstractMatcher;
class ContainsMatcher extends AbstractMatcher
{
/**
* {@inheritdoc}
*/
public function matchesClass(\ReflectionClass $class, array $arguments) : bool
{
list($contains) = $arguments;
return (strpos($class->name, $contains) !== false);
}
/**
* {@inheritdoc}
*/
public function matchesMethod(\ReflectionMethod $method, array $arguments) : bool
{
list($contains) = $arguments;
return (strpos($method->name, $contains) !== false);
}
}
```
Module
```php
class AppModule extends AbstractAppModule
{
protected function configure()
{
// ...
$this->bindInterceptor(
$this->matcher->any(), // In any class,
new ContainsMatcher('user'), // When 'user' contained in method name
[UserLogger::class] // Bind UserLogger class
);
}
};
```
# Resource
A BEAR.Sunday application is [RESTful](http://en.wikipedia.org/wiki/Representational_state_transfer) and is made up of a collection of resources connected by links.
## Object as a service
An HTTP method is mapped to a PHP method in the `ResourceObject` class.
It transfers its resource state as a resource representation from stateless request.
([Representational State Transfer)](http://en.wikipedia.org/wiki/REST)
Here are some examples of a resource object:
```php
class Index extends ResourceObject
{
public $code = 200;
public $headers = [];
public function onGet(int $a, int $b): static
{
$this->body = [
'sum' => $a + $b // $_GET['a'] + $_GET['b']
] ;
return $this;
}
}
```
```php
class Todo extends ResourceObject
{
public function onPost(string $id, string $todo): static
{
$this->code = 201; // status code
$this->headers = [ // header
'Location' => '/todo/new_id'
];
return $this;
}
}
```
The PHP resource class has URIs such as `page://self/index` similar to the URI of the web, and conforms to the HTTP method `onGet`,` onPost`, `onPut`,` onPatch`, `onDelete` interface.
$_GET for `onGet` and $_POST for `onPost` are passed to the arguments of the method depending on the variable name, and the methods of `onPut`,` onPatch`, `onDelete` are content. The value that can be handled according to `content-type`(`x-www-form-urlencoded` or `application/json`) is an argument.
The resource state (`code`,`headers` or`body`) is handled by these method using the given parameters. Then the resource class returns itself(`$this`).
## URI
URIs are mapped to PHP classes. Applications use the URI instead of the class name to access resources.
| URI | Class |
|-----+-------|
| page://self/ | Koriym\Todo\Resource\Page\Index |
| page://self/index | Koriym\Todo\Resource\Page\Index |
| app://self/blog/posts?id=3 | Koriym\Todo\Resource\App\Blog\Posts |
## Scheme
The equivalent to a MVC model is an `app` resource. A resource functions as an internal API, but as it is designed using REST it also works as an external API transport.
The `page` resource carries out a similar role as a page controller which is also a resource. Unlike `app` resources, it receives external requests and generates representations for output.
| URI | Class |
|-----+-------|
| page://self/index | Koriym\Todo\Resource\Page\Index |
| app://self/blog/posts | Koriym\Todo\Resource\App\Blog\Posts |
## Method
Resources have 6 interfaces conforming to HTTP methods.[^method]
[^method]: REST methods are not a mapping to CRUD. They are divided into two categories: safe ones that do not change the resource state, or idempotent ones.
### GET
Reads resources. This method does not provide any changing of the resource state. A safe method with no possible side affects.
### POST
The POST method requests processing of the representation contained in the request. For example, adding a new resource to a target URI or adding a representation to an existing resource. Unlike PUT, requests do not have [idempotence](https://ja.wikipedia.org/wiki/%E5%86%AA%E7%AD%89), and multiple consecutive executions will not produce the same result.
### PUT
Replaces the resource with the payload of the request at the requested URI. If the target resource does not exist, it is created. Unlike POST, PUT is idempotent.
### PATCH
Performs resource updates, but unlike PUT, it applies a delta rather than replacing the entire resource.
### DELETE
Resource deletion. Has idempotence just like PUT.
### OPTIONS
Get information on parameters and responses required for resource request. It is as secure as GET method.
#### List of method properties
| Methods | [Safe](https://developer.mozilla.org/en-US/docs/Glossary/Safe/HTTP) | [Idempotent](https://developer.mozilla.org/en-US/docs/Glossary/Idempotent) | [Cacheable](https://developer.mozilla.org/en-US/docs/Glossary/cacheable)
|-|-|-|-|-
| GET | Yes | Yes | Yes
| POST | No | No | No
| PUT | No | Yes | No
| PATCH | No | No | No
| DELETE | No | Yes | No
| OPTIONS | Yes | Yes | No
## Parameters
The response method argument is passed the request value corresponding to the variable name.
```php
class Index extends ResourceObject
{
// $_GET['id'] to $id
public function onGet(int $id): static
{
}
// $_POST['name'] to $name
public function onPost(string $name): static
{
}
```
See [Resource Parameters](resource_param.html) for other methods and how to pass external variables such as cookies as parameters.
## Rendering and transfer
The request method of a ResourceObject is not concerned with the representation of the resource. The injected renderer generates the representation of the resource and the responder outputs it. See [Rendering and Transferring](resource_renderer.html) for details.
## Client
Use the resource client to request other resources. This request executes a request to the `app://self/blog/posts` resource with the query `?id=1`.
```php
use BEAR\Sunday\Inject\ResourceInject;
class Index extends ResourceObject
{
use ResourceInject;
public function onGet(): static
{
$this->body = [
'posts' => $this->resource->get('app://self/blog/posts', ['id' => 1])
];
}
}
```
Other historical notations include the following
```php
// PHP 5.x and up
$posts = $this->resource->get->uri('app://self/posts')->withQuery(['id' => 1])->eager->request();
// PHP 7.x and up
$posts = $this->resource->get->uri('app://self/posts')(['id' => 1]);
// you can omit `get`
$posts = $this->resource->uri('app://self/posts')(['id' => 1]);
// bear/resource 1.11 and up
$posts = $this->resource->get('app://self/posts', ['id' => 1]);
```
## Lazy evaluation
The above is an `eager` request that makes the request immediately, but it is also possible to generate a request and delay execution instead of the request result.
```php
$request = $this->resource->get->uri('app://self/posts')->withQuery(['id' => 1]); // callable
$posts = $request();
```
When this request is embedded in a template or resource, it is evaluated lazily. That is, when it is not evaluated, the request is not made and has no execution cost.
```php
$this->body = [
'lazy' => $this->resource->get->uri('app://self/posts')->withQuery(['id' => 3])
];
```
The `#[Embed]` attribute provides a declarative way to achieve the same lazy embedding. See [Resource Link](resource_link.html) for details.
## Cache
Along with regular TTL caching, we support REST client caching and advanced partial caching (doughnut caching), including CDN. See [cache](cache.html) for details. Also see the previous [resource(v1)](resourcev1.html#Resource Cache) document for the previous `@Cacheable` annotation.
## Link
One important REST constraint is resource linking; ResourceObject supports both internal and external linking. See [Resource Linking](resource_link.html) for details.
## BEAR.Resource
The functionality of the BEAR.Sunday resource object is also available in a stand-alone package for stand-alone use: BEAR.Resource [README](https://github.com/bearsunday/BEAR.Resource/blob/1.x/README.ja.md).
---
## Development
# Database
The following modules are available for database use, with different problem solving methods. They are all independent libraries for SQL based on [PDO](https://www.php.net/manual/ja/intro.pdo.php).
* ExtendedPdo with PDO extended ([Aura.sql](https://github.com/auraphp/Aura.Sql))
* Query Builder ([Aura.SqlQuery](https://github.com/auraphp/Aura.SqlQuery))
* Binding PHP interface and SQL execution ([Ray.MediaQuery](database_media.html))
Having static SQL in a file[^locator] makes it easier to use and tune with other SQL tools. SqlQuery can dynamically assemble queries, but the rest of the library is for basic static SQL execution. Ray.MediaQuery can also replace parts of the SQL with those assembled by the builder.
[^locator]: [query-locater](https://github.com/koriym/Koriym.QueryLocator) is a library for handling SQL as files, which is useful with Aura.Sql.
## Module
Modules are provided for using the database. They are all independent libraries for SQL.
* [Ray.AuraSqlModule](database_aura.html)
* [Ray.MediaQuery](database_media.html)
`Ray.AuraSqlModule` is a PDO extension [Aura.Sql](https://github.com/auraphp/Aura.Sql) and a query builder [Aura.SqlQuery](https://github.com/auraphp/) SqlQuery, plus a low-level module that provides pagination functionality.
`Ray.MediaQuery` is a high-performance DB access framework that generates and injects SQL execution objects from user-provided interfaces and SQL [^doma] .
[^doma]: The mechanism is similar to Java's DB access framework [Doma](https://doma.readthedocs.io/en/latest/basic/#examples).
## Other
* [DBAL](database_dbal.html)
* [CakeDb](database_cake.html)
* [Ray.QueryModule](https://github.com/ray-di/Ray.QueryModule/blob/1.x/README.md)
`DBAL` is Doctrine and `CakeDB` is CakePHP's DB library. `Ray.QueryModule` is an earlier library of Ray.MediaQuery that converts SQL to anonymous functions.
## CQRS Read Model
* [BEAR.Projection](https://github.com/bearsunday/BEAR.Projection)
`BEAR.Projection` provides SQL-based projections mapped to typed value objects. Projections are exposed as resources via the `query://` scheme and can be embedded with `#[Embed]` for [parallel execution](async.html).
```php
#[Embed(rel: 'profile', src: 'query://self/user_profile{?id}')]
#[Embed(rel: 'orders', src: 'query://self/user_orders{?id}')]
public function onGet(string $id): static
```
----
# Router
The router converts resource requests for external contexts such as Web and console into resource requests inside BEAR.Sunday.
```php?start_inline
$request = $app->router->match($GLOBALS, $_SERVER);
echo (string) $request;
// get page://self/user?name=bear
```
## Web Router
The default web router accesses the resource class corresponding to the HTTP request path (`$_SERVER['REQUEST_URI']`).
For example, a request of `/index` is accessed by a PHP method corresponding to the HTTP method of the `{Vendor name}\{Project name}\Resource\Page\Index` class.
The Web Router is a convention-based router. No configuration or scripting is required.
```php?start_inline
namespace MyVendor\MyProject\Resource\Page;
// page://self/index
class Index extends ResourceObject
{
public function onGet(): static // GET request
{
}
}
```
## CLI Router
In the `cli` context, the argument from the console is "input of external context".
```bash
php bin/page.php get /
```
The BEAR.Sunday application works on both the Web and the CLI.
## Multiple words URI
The path of the URI using hyphens and using multiple words uses the class name of Camel Case.
For example `/wild-animal` requests are accessed to the `WildAnimal` class.
## Parameters
The name of the PHP method executed corresponding to the HTTP method and the value passed are as follows.
| HTTP method | PHP method | Parameters |
|---|---|---|
| GET | onGet | $_GET |
| POST | onPost | $_POST or ※ standard input |
| PUT | onPut | ※ standard input |
| PATCH | onPatch | ※ standard input |
| DELETE | onDelete | ※ standard input |
There are two media types available for request:
* `application/x-www-form-urlencoded` // param1=one¶m2=two
* `application/json` // {"param1": "one", "param2": "one"}
Please also see the [PUT method support](http://php.net/manual/en/features.file-upload.put-method.php) of the PHP manual.
## Method Override
There are firewalls that do not allow HTTP PUT traffic or HTTP DELETE traffic.
To deal with this constraint, you can send these requests in the following two ways.
* `X-HTTP-Method-Override` Send a PUT request or DELETE request using the header field of the POST request.
* `_method` Use the URI parameter. ex) POST /users?...&_method=PUT
## Aura Router
To receive the request path as a parameter, use Aura Router.
```bash
composer require bear/aura-router-module ^2.0
```
Install `AuraRouterModule` with the path of the router script.
```php?start_inline
use BEAR\Package\AbstractAppModule;
use BEAR\Package\Provide\Router\AuraRouterModule;
class AppModule extends AbstractAppModule
{
protected function configure()
{
// ...
$this->install(new AuraRouterModule($appDir . '/var/conf/aura.route.php'));
}
}
```
Delete cached DI files to activate new router.
```
rm -rf var/tmp/*
```
### Router Script
Router scripts set routes for `Map` objects passed globally.
You do not need to specify a method for routing.
The first argument specifies the path as the root name and the second argument specifies the path containing the place folder of the named token.
`var/conf/aura.route.php`
```php
route('/blog', '/blog/{id}');
$map->route('/user', '/user/{name}')->tokens(['name' => '[a-z]+']);
$map->route('/blog/comment', '/blog/{id}/comment');
```
* In the first line, accessing `/blog/bear` will be accessed as `page://self/blog?id=bear`.
(= `Blog` class's` onGet($id)` method with the value `$id`=`bear`.)
* `token` is used to restrict parameters with regular expressions.
* `/blog/{id}/comment` to route `Blog\Comment` class.
### Preferred router
If it is not routed by the Aura router, a web router will be used.
In other words, it is OK to prepare the router script only for the URI that passes the parameters in the path.
### Parameter
`Aura router` have various methods to obtain parameters from the path.
### Custom Placeholder Token Matching
The script below routes only when `{date}` is in the proper format.
```php?start_inline
$map->route('/calendar/from', '/calendar/from/{date}')
->tokens([
'date' => function ($date, $route, $request) {
try {
new \DateTime($date);
return true;
} catch(\Exception $e) {
return false;
}
}
]);
```
### Optional Placeholder Tokens
Sometimes it is useful to have a route with optional placeholder tokens for attributes. None, some, or all of the optional values may be present, and the route will still match.
To specify optional attributes, use the notation {/attribute1,attribute2,attribute3} in the path. For example:
ex）
```php?start_inline
$map->route('archive', '/archive{/year,month,day}')
->tokens([
'year' => '\d{4}',
'month' => '\d{2}',
'day' => '\d{2}',
]);
```
Please note that there is the first slash **inside** of the place holder.
Then all the paths below are routed to 'archive' and the value of the parameter is appended.
- `/archive : ['year' => null, 'month' => null, 'day' => null]`
- `/archive/1979 : ['year' => '1979', 'month' => null, 'day' => null]`
- `/archive/1979/11 : ['year' => '1979', 'month' => '11', 'day' => null]`
- `/archive/1979/11/07 : ['year' => '1979', 'month' => '11', 'day' => '07']`
Optional parameters are **options in the order of**. In other words, you can not specify "day" without "month".
### Wildcard Attributes
Sometimes it is useful to allow the trailing part of the path be anything at all. To allow arbitrary trailing path segments on a route, call the wildcard() method. This will let you specify the attribute name under which the arbitrary trailing values will be stored.
```php?start_inline
$map->route('wild', '/wild')
->wildcard('card');
```
All slash-separated path segments after the {id} will be captured as an array in the in wildcard attribute. For example:
- `/wild : ['card' => []]`
- `/wild/foo : ['card' => ['foo']]`
- `/wild/foo/bar : ['card' => ['foo', 'bar']]`
- `/wild/foo/bar/baz : ['card' => ['foo', 'bar', 'baz']]`
For other advanced routes, please refer to Aura Router's [defining-routes](https://github.com/auraphp/Aura.Router/blob/3.x/docs/defining-routes.md).
## Generating Paths From Routes
You can generate a URI from the name of the route and the value of the parameter.
```php?start_inline
use BEAR\Sunday\Extension\Router\RouterInterface;
class Index extends ResourceObject
{
/**
* @var RouterInterface
*/
private $router;
public function __construct(RouterInterface $router)
{
$this->router = $router;
}
public function onGet(): static
{
$userLink = $this->router->generate('/user', ['name' => 'bear']);
// '/user/bear'
```
### Request Method
It is not necessary to specify a request method.
### Request Header
Normally request headers are not passed to Aura.Router, but installing `RequestHeaderModule` allows Aura.Router to match using headers.
```php
$this->install(new RequestHeaderModule());
```
## Custom Router Component
Implement [RouterInterface](https://github.com/bearsunday/BEAR.Sunday/blob/1.x/src/Extension/Router/RouterInterface.php) with by referring to [BEAR.AuraRouterModule](https://github.com/bearsunday/BEAR.AuraRouterModule).
---
*[This document](https://github.com/bearsunday/bearsunday.github.io/blob/master/manuals/1.0/en/router.md) needs to be proofread by native speaker. *
# Production
For BEAR.Sunday's default `prod` binding, the application customizes the module according to each [deployment environment](https://en.wikipedia.org/wiki/Deployment_environment) and performs the binding.
## Default ProdModule
The default `prod` binding binds the following interfaces:
* Error page generation factory
* PSR logger interface
* Local cache
* Distributed cache
See [ProdModule.php](https://github.com/bearsunday/BEAR.Package/blob/1.x/src/Context/ProdModule.php) in BEAR.Package for details.
## Application's ProdModule
Customize the application's `ProdModule` in `src/Module/ProdModule.php` against the default ProdModule. Error pages and distributed caches are particularly important.
```php
install(new PackageProdModule); // Default prod settings
$this->override(new OptionsMethodModule); // Enable OPTIONS method in production as well
$this->install(new CacheVersionModule('1')); // Specify resource cache version
// Custom error page
$this->bind(ErrorPageFactoryInterface::class)->to(MyErrorPageFactory::class);
}
}
```
## Cache
There are two types of caches: a local cache and a distributed cache that is shared between multiple web servers.
Both caches default to [PhpFileCache](https://www.doctrine-project.org/projects/doctrine-cache/en/1.10/index.html#phpfilecache).
### Local Cache
The local cache is used for caches that do not change after deployment, such as annotations, while the distributed cache is used to store resource states.
### Distributed Cache
To provide services with two or more web servers, a distributed cache configuration is required.
Modules for each of the popular [memcached](http://php.net/manual/en/book.memcached.php) and [Redis](https://redis.io) cache engines are provided.
### Memcached
```php
install(new StorageMemcachedModule($memcachedServers));
// Install Prod logger
$this->install(new ProdLoggerModule);
// Install default ProdModule
$this->install(new PackageProdModule);
}
}
```
### Redis
```php?start_inline
// redis
$redisServer = 'localhost:6379'; // {host}:{port}
$this->install(new StorageRedisModule($redisServer));
```
In addition to simply updating the cache by TTL for storing resource states, it is also possible to operate (CQRS) as a persistent storage that does not disappear after the TTL time.
In that case, you need to perform persistent processing with `Redis` or prepare your own storage adapter for other KVS such as Cassandra.
### Specifying Cache Time
To change the default TTL, install `StorageExpiryModule`.
```php?start_inline
// Cache time
$short = 60;
$medium = 3600;
$long = 24 * 3600;
$this->install(new StorageExpiryModule($short, $medium, $long));
```
### Specifying Cache Version
Change the cache version when the resource schema changes and compatibility is lost. This is especially important for CQRS operation that does not disappear over TTL time.
```
$this->install(new CacheVersionModule($cacheVersion));
```
To discard the resource cache every time you deploy, it is convenient to assign a time or random value to `$cacheVersion` so that no change is required.
## Logging
`ProdLoggerModule` is a resource execution log module for production. When installed, it logs requests other than GET to the logger bound to `Psr\Log\LoggerInterface`.
If you want to log on a specific resource or specific state, bind a custom log to [BEAR\Resource\LoggerInterface](https://github.com/bearsunday/BEAR.Resource/blob/1.x/src/LoggerInterface.php).
```php
use BEAR\Resource\LoggerInterface;
use Ray\Di\AbstractModule;
final class MyProdLoggerModule extends AbstractModule
{
protected function configure(): void
{
$this->bind(LoggerInterface::class)->to(MyProdLogger::class);
}
}
```
The `__invoke` method of [LoggerInterface](https://github.com/bearsunday/BEAR.Resource/blob/1.x/src/LoggerInterface.php) passes the resource URI and resource state as a `ResourceObject` object, so log the necessary parts based on its contents.
Refer to the [existing implementation ProdLogger](https://github.com/bearsunday/BEAR.Resource/blob/1.x/src/ProdLogger.php) for creation.
## Deployment
### ⚠️ Avoid Overwriting Updates
#### When deploying to a server
* Overwriting a running project folder with `rsync` or similar poses a risk of inconsistency with caches and on-demand generated files, and can exceed capacity on high-load sites.
Set up in a separate directory for safety and switch if the setup is successful.
* You can use the [BEAR.Sunday recipe](https://github.com/bearsunday/deploy) of [Deployer](http://deployer.org/).
#### When deploying to the cloud
* It is recommended to incorporate compilation into CI as the compiler outputs exit code 1 when it finds dependency issues and 0 when compilation succeeds.
### Compilation Recommended {: #compilation }
When setting up, you can **warm up** the project: create static cache files for DI/AOP and annotations in advance, and write optimized `autoload.php` and `preload.php`.
**Principle: compile on the deploy target when you can** (at warm-up / health-check time). Real environment values — paths, environment variables — are reflected as-is, so values bake in correctly and no writable-path override is needed.
**Exception: environments that need ahead-of-time compilation** (serverless, a read-only app root, or a fixed path such as `/tmp`). Because you compile where the real services are unreachable, combine [changing writable paths](#writable-paths), AOT script reuse, and `.compile.php` (to stub the unreachable services), and **do not bake values that vary at runtime (hosts, tokens) — resolve them at runtime.**
A build script names the application; it does not boot it (BEAR.Package 1.22+; the skeleton ships `bin/compile.php`).
```php
getInstance(AppInterface::class);
+ $app = Injector::getInstance($context, $writeDir)->getInstance(AppInterface::class);
// src/Injector.php
-use BEAR\Package\Injector\PackageInjector;
+use BEAR\Package\Injector as PackageInjector;
- public static function getInstance(
- string $context, string|null $tmpDir = null, string|null $logDir = null
- ): InjectorInterface
- {
- $meta = new Meta(__NAMESPACE__, $context, dirname(__DIR__), $tmpDir, $logDir);
- $cacheNamespace = str_replace('/', '_', $meta->appDir) . $context;
- $cache = (new LocalCacheProvider($meta->tmpDir . '/injector', $cacheNamespace))->get();
-
- return PackageInjector::getInstance($meta, $context, $cache);
- }
+ public static function getInstance(string $context, string|null $writeDir = null): InjectorInterface
+ {
+ return PackageInjector::getInstance(__NAMESPACE__, $context, dirname(__DIR__), null, $writeDir);
+ }
```
`BEAR\Package\Injector` builds the `Meta` and the injector cache pool from the write directory, so the skeleton's own `Meta` / `LocalCacheProvider` lines go away. Development entry points pass nothing and keep the default paths. Reading environment variables is the entry point's business, not the framework's.
The build takes the directory as an argument, the runtime as an environment variable:
```text
build php bin/compile.php prod-app /tmp
runtime APP_WRITE_DIR=/tmp
php-fpm env[APP_WRITE_DIR] = /tmp
docker --env APP_WRITE_DIR=/tmp
```
With `/tmp` as the write directory, the layout is:
```text
{appDir}/var/tmp/{context}/di compiled DI scripts, in the artifact
/tmp/MyVendor/MyProject/{context}/tmp query repository cache, serialized injector
/tmp/MyVendor/MyProject/{context}/log
```
The application and the context are in the path because local cache keys are resource URIs: two applications or two contexts sharing one directory would answer with each other's entries.
Compiled DI scripts stay under `appDir` and ship inside the artifact. A new instance starts with an empty `/tmp`, so following the write directory would compile again on every cold start - 0.38s against 0.018s on a five-resource application.
If the boot is given a different write directory than the build used, the DI scripts are compiled again instead of read from the old paths: the compile fails if the artifact is read-only, and emits a `Compiled DI scripts on demand` notice if it is writable.
Requires BEAR.Package 1.22+. Background: [BEAR.Package#491](https://github.com/bearsunday/BEAR.Package/pull/491).
### autoload.php
An optimized autoload file is output to `{project_path}/autoload.php`. It is lighter than the `vendor/autoload.php` produced by `composer dump-autoload --optimize` and reduces per-request autoload cost **when you do not use preload**.
Note: If you use `preload.php`, most classes are already loaded at startup, so this `autoload.php` is essentially unnecessary — use the `vendor/autoload.php` generated by Composer. In other words, `autoload.php` is a fallback for environments that cannot use preload.
### preload.php
An optimized preload.php file is output to `{project_path}/preload.php`.
To enable preloading, you need to specify [opcache.preload](https://www.php.net/manual/en/opcache.configuration.php#ini.opcache.preload) and [opcache.preload](https://www.php.net/manual/en/opcache.configuration.php#ini.opcache.preload-user) in php.ini. It is a feature supported in PHP 7.4, but it is unstable in the initial versions of `7.4`. Let's use the latest version of `7.4.4` or higher.
Example)
```
opcache.preload=/path/to/project/preload.php
opcache.preload_user=www-data
```
Note: Please refer to the [benchmark](https://github.com/bearsunday/BEAR.HelloworldBenchmark/wiki/Intel-Core-i5-3.8-GHz-iMac-(Retina-5K,-27-inch,-2017)---PHP-7.4.4) for performance benchmarks.
### .compile.php
When there are classes that cannot be generated in a non-production environment (for example, a ResourceObject that requires successful authentication to complete injection), you can compile them by describing dummy class loading in the root `.compile.php` file, which is only loaded during compilation. **Its purpose is to let construction succeed at compile time, so its contents should be null objects (do-nothing implementations).** This applies not only to ahead-of-time builds (real services unreachable) but also to resources that need per-request state such as authentication, which is absent during compilation even when you compile on the deploy target. Keep value fakes (`$_SERVER['X'] = 'fake'`, etc.) to the minimum needed to pass construction, and never use them for values that must be real at runtime (they get baked in).
**Note (BEAR.Package 1.21+):** `Compiler::fromInjector()` does not load `.compile.php` automatically (the deprecated `bear.compile` did). Load it from your `bin/compile.php` as shown above.
.compile.php
Example) If there is an AuthProvider that throws an exception when authentication cannot be obtained in the constructor, you can create an empty class as follows and load it in .compile.php:
/tests/Null/AuthProvider.php
```php
module.svg
```
## Bootstrap Performance Tuning
[immutable_cache](https://pecl.php.net/package/immutable_cache) is a PECL package for caching immutable values in shared memory. It is based on APCu but is faster than APCu because it stores immutable values such as PHP objects and arrays in shared memory. Additionally, installing PECL's [Igbinary](https://www.php.net/manual/en/book.igbinary.php) with either APCu or immutable_cache can reduce memory usage and further improve performance.
Currently, there are no dedicated cache adapters available. Please refer to [ImmutableBootstrap](https://github.com/koriym/BEAR.Hello/commit/507d1ee3ed514686be2d786cdaae1ba8bed63cc4) to create and call a dedicated Bootstrap. This allows you to minimize initialization costs and achieve maximum performance.
### php.ini
```
// Extensions
extension="apcu.so"
extension="immutable_cache.so"
extension="igbinary.so"
// Specifying serializer
apc.serializer=igbinary
immutable_cache.serializer=igbinary
```
`````
----
# Test
Proper testing makes software better with continuity. A clean application of BEAR.Sunday is test friendly, with all dependencies injected and crosscutting interests provided in the AOP.
## Run test
Run `vendor/bin/phpunit` or `composer test`. Other commands are as follows.
```
composer test // phpunit test
composer tests // test + sa + cs
composer coverage // test coverage
composer pcov // test coverage (pcov)
composer sa // static analysis
composer cs // coding standards check
composer cs-fix // coding standards fix
```
## Resource test
**Everything is a resource** - BEAR.Sunday application can be tested with resoure access.
This is a test that tests that `201 (Created)` will be returned by POSTing `['title' => 'test']` to URI `page://self/todo` of `Myvendor\MyProject` application in `html-app` context.
```php
resource = $injector->getInstance(ResourceInterface::class);
}
public function testOnPost(): void
{
$page = $this->resource->post('page://self/todo', ['title' => 'test']);
$this->assertSame(StatusCode::CREATED, $page->code);
}
}
```
## Test Double
A Test Double is a substitute that replaces a component on which the software test object depends. Test doubles can have the following patterns
* Stub (provides "indirect input" to the test target)
* Mock ( validate "indirect output" from the test target inside a test double)
* Spy (records "indirect output" from the target to be tested)
* Fake (simpler implementation that works closer to the actual object)
* _Dummy_ (necessary to generate the test target but no call is made)
### Test Double Binding
There are two ways to change the bundling for a test. One is to change the bundling across all tests in the context module, and the other is to temporarily change the bundling only for a specific purpose within one test only.
#### Context Module
Create a ``TestModule`` to make the `test` context available in bootstrap.
```php
class TestModule extends AbstractModule
{
public function configure(): void
{
$this->bind(DateTimeInterface::class)->toInstance(new DateTimeImmutable('1970-01-01 00:00:00'));
$this->bind(Auth::class)->to(FakeAuth::class);
}
}
```
Injector with test context.
```php
$injector = Injector::getInstance('test-hal-app', $module);
```
#### Temporary binding change
Temporary bundle changes for a single test specify the bundle to override with `Injector::getOverrideInstance`.
```php
public function testBindFake(): void
{
$module = new class extends AbstractModule {
protected function configure(): void
{
$this->bind(FooInterface::class)->to(FakeFoo::class);
}
}
$injector = Injector::getOverrideInstance('hal-app', $module);
}
```
### Mock
```php
public function testBindMock(): void
{
$mock = $this->createMock(FooInterface::class);
// expect that update() will be called once and the parameter will be the string 'something'.
mock->expects($this->once())
->method('update')
->with($this->equalTo('something'));
$module = new class($mock) extends AbstractModule {
public function __construct(
private FooInterface $foo
){}
protected function configure(): void
{
$this->bind(FooInterface::class)->toInstance($this->foo);
}
};
$injector = Injector::getOverrideInstance('hal-app', $module);
}
```
### spy
Installs a `SpyModule` by specifying the interface or class name of the spy target. [^spy-module] After running the SUT containing the spy target, verify the number of calls and the value of the calls in the spy log.
[^spy-module]: [ray/test-double](https://github.com/ray-di/Ray.TestDouble) must be installed to use SpyModule.
```php
public function testBindSpy(): void
{
$module = new class extends AbstractModule {
protected function configure(): void
{
$this->install(new SpyModule([FooInterface::class]));
}
};
$injector = Injector::getOverrideInstance('hal-app', $module);
$resource = $injector->getInstance(ResourceInterface::class);
// Spy logs of FooInterface objects are logged, whether directly or indirectly.
$resource->get('/');
// Spyログの取り出し
$spyLog = $injector->getInstance(\Ray\TestDouble\LoggerInterface::class);
// @var arrayBatch service management commands | Individual dev, team dev | | **Docker** | macOS, Windows, Linux | Container-based complete environment reproduction, CI/CD friendly | Team dev, CI/CD, production-like | | **Manual** | All OS | Use existing environment as-is, fine-grained control | Existing infrastructure, constrained environments | --- ## Environment Setup with malt ### Overview **malt** is a development environment management tool based on Homebrew. It consolidates configuration and data directly under the project, achieving local completion. **Key Features** * **Completely Local**: All configuration and data stored within the project * **Clean Deletion**: Folder deletion = environment deletion * **Dedicated Port Commands**: Aliases like `mysql@3306` / `redis@6379` * **No Global Pollution**: No impact on system MySQL/Redis etc. * **Configuration Visibility**: Configuration files can be shared and reviewed within the project * **Batch Service Management**: `malt start` / `malt stop` can start/stop related services together ### Prerequisites * macOS or Linux (including WSL2) * Homebrew installed ### Installation ```bash # Add Homebrew taps brew tap shivammathur/php brew tap shivammathur/extensions brew tap koriym/malt # Install malt brew install malt ``` ### Basic Operations (Shortest Path) ```bash malt init && malt install && malt create && malt start source <(malt env) ``` ### Configuration Files ```text malt.json # malt configuration malt/ conf/ my_3306.cnf # MySQL configuration php.ini # PHP configuration httpd_8080.conf # Apache configuration nginx_80.conf # Nginx configuration ``` These files can be included in your project for team environment sharing. ### Service Management ```bash # Status check malt status # Start / stop / restart all services malt start malt stop malt restart # Specific services only malt start mysql malt stop nginx ``` ### Database Operations ```bash mysql@3306 # Connect to project-specific MySQL redis@6379 # Connect to project-specific Redis mysql@3306 -e "CREATE DATABASE IF NOT EXISTS myapp" ``` > **Important**: `mysql@3306` is **project-specific connection**. It's isolated from the system's global MySQL. --- ## Environment Setup with Docker ### Overview Docker provides OS-independent, consistent development environments. **Docker Considerations:** - **Global Command Conflicts**: The system `mysql` command points to global MySQL installation - **Container-specific Access**: Requires specific connection methods for Docker container databases - **Port Conflict Risk**: Ports like 3306 may conflict with system services - **macOS File Access**: Host-container file mount performance degradation, especially noticeable during bulk file operations (builds, tests) - **Security**: `MYSQL_ALLOW_EMPTY_PASSWORD` should be limited to development use only ### Prerequisites - [Docker Desktop](https://www.docker.com/products/docker-desktop) installed - Docker Compose available ### Basic docker-compose.yml ```yaml version: '3.8' services: mysql: image: mysql:8.0 environment: MYSQL_ROOT_PASSWORD: "" MYSQL_ALLOW_EMPTY_PASSWORD: "yes" MYSQL_DATABASE: myapp ports: - "3306:3306" volumes: - mysql_data:/var/lib/mysql - ./docker/mysql/init.sql:/docker-entrypoint-initdb.d/init.sql command: --default-authentication-plugin=mysql_native_password healthcheck: test: ["CMD", "mysqladmin", "ping", "-h", "localhost"] interval: 10s timeout: 5s retries: 3 redis: image: redis:alpine ports: - "6379:6379" memcached: image: memcached:alpine ports: - "11211:11211" volumes: mysql_data: ``` ### Usage ```bash # Start environment docker-compose up -d # Check status docker-compose ps # Check logs docker-compose logs mysql # Stop environment docker-compose stop # Complete removal (including data) docker-compose down -v ``` ### Database Connection ```bash # Connect from host (port specification required) mysql -h 127.0.0.1 -P 3306 -u root # Connect from within container (recommended) docker-compose exec mysql mysql -u root ``` **Warning**: If `mysql` is installed on your system, running just `mysql` will connect to your system's MySQL, not the Docker container. To access the Docker database, you must either specify host/port or execute from within the container. --- ## Manual Environment Setup ### PHP ```bash # macOS (Homebrew) brew install php@8.4 brew install composer # Ubuntu/Debian sudo apt update sudo apt install php8.4 php8.4-{cli,mysql,mbstring,xml,zip,curl} curl -sS https://getcomposer.org/installer | php sudo mv composer.phar /usr/local/bin/composer # CentOS/RHEL sudo dnf install php php-{cli,mysql,mbstring,xml,zip,curl} ``` ### MySQL ```bash # macOS (Homebrew) brew install mysql@8.0 brew services start mysql@8.0 # Ubuntu/Debian sudo apt install mysql-server-8.0 sudo systemctl start mysql # CentOS/RHEL sudo dnf install mysql-server sudo systemctl start mysqld ``` ### Useful PHP Extensions for Development ```bash # Xdebug (debugging) brew install shivammathur/extensions/xdebug@8.4 # Homebrew sudo apt install php8.4-xdebug # Ubuntu # XHProf (profiling) brew install shivammathur/extensions/xhprof@8.4 # Homebrew sudo apt install php8.4-xhprof # Ubuntu # Redis brew install shivammathur/extensions/redis@8.4 # Homebrew sudo apt install php8.4-redis # Ubuntu # APCu (caching) brew install shivammathur/extensions/apcu@8.4 # Homebrew sudo apt install php8.4-apcu # Ubuntu ``` **Important**: Xdebug and XHProf impact performance, so avoid leaving them enabled all the time. When you configure them, Xdebug uses `zend_extension=xdebug.so`, while XHProf uses `extension=xhprof.so`; enable them from the CLI only when needed. ```bash # Enable Xdebug only when debugging php -dzend_extension=xdebug.so -S 127.0.0.1:8080 -t public # Enable XHProf only when profiling php -dextension=xhprof.so script.php # Disable Xdebug when running Composer (recommended) XDEBUG_MODE=off composer install # Or override the PHP ini setting php -dxdebug.mode=off /usr/local/bin/composer install ``` --- ## BEAR.Sunday Quick Start Example ```bash composer create-project bear/skeleton my-app cd my-app malt init && malt install && malt create && malt start source <(malt env) ``` --- ## Project-specific Configuration ### .env (Example) ```dotenv # MySQL DB_HOST=127.0.0.1 DB_PORT=3306 DB_NAME=myapp DB_USER=root DB_PASS= DB_DSN=mysql:host=127.0.0.1;port=3306;dbname=myapp # SQLite (switching example) # DB_DSN=sqlite:var/db.sqlite3 # Redis REDIS_HOST=127.0.0.1:6379 # Memcached MEMCACHED_HOST=127.0.0.1:11211 ``` ### Migration (Phinx Example) ```bash composer require --dev robmorgan/phinx ./vendor/bin/phinx init ./vendor/bin/phinx create MyMigration ./vendor/bin/phinx migrate ``` --- ## Development Server ### PHP Built-in Server ```bash # Start on port 8080 php -S 127.0.0.1:8080 -t public # Enable Xdebug only when debugging php -dzend_extension=xdebug.so -S 127.0.0.1:8080 -t public ``` ### malt Server ```bash # Choose Apache / Nginx and start malt start apache # http://127.0.0.1:8080 malt start nginx # http://127.0.0.1:80 # Check services malt status # Start/stop all services malt start malt stop # Individual stop malt stop apache malt stop nginx ``` --- ## Troubleshooting ### Port Conflicts ```bash # macOS/Linux lsof -i :3306 netstat -tulpn | grep :3306 # Kill the process kill -9
* Halo Home (Border and Tools Display)
* Resource State
* Resource Representation
* Profile
You can try a demo of Halo in the [demo](/docs/demo/halo/).
### Performance Monitoring
Halo also displays performance information about the resource, including execution time, memory usage, and a link to the profiler.
### Installation
To enable profiling, you need to install [xhprof](https://www.php.net/manual/en/intro.xhprof.php), which helps identify performance bottlenecks.
```
pecl install xhprof
// Also add 'extension=xhprof.so' to your php.ini file
```
To visualize and graphically display call graphs, you need to install [graphviz](https://graphviz.org/download/).
Example: [Call Graph Demo](/docs/demo/halo/callgraph.svg)
```
// macOS
brew install graphviz
// Windows
// Download and install the installer from the graphviz website
// Linux (Ubuntu)
sudo apt-get install graphviz
```
In your application, create a Dev context module and install the `HaloModule`.
```php
class DevModule extends AbstractModule
{
protected function configure(): void
{
$this->install(new HaloModule($this));
}
}
```
---
# Form
Ray.WebFormModule provides aspect-oriented web form validation powered by [Aura.Input](https://github.com/auraphp/Aura.Input) and [Ray.Di](https://github.com/ray-di/Ray.Di). Form fields, validation rules, submitted values, and rendering helpers are collected in a single form class so the form is easy to test and change.
## Installation
Install `ray/web-form-module` with Composer.
```bash
composer require ray/web-form-module
```
Install `WebFormModule` in your application module.
```php
use Ray\Di\AbstractModule;
use Ray\WebFormModule\WebFormModule;
class AppModule extends AbstractModule
{
protected function configure()
{
$this->install(new WebFormModule());
}
}
```
The legacy `Ray\WebFormModule\AuraInputModule` class remains available as a thin subclass of `WebFormModule` for backward compatibility. New code should use `WebFormModule`.
## Form Class
A self-initializing form class defines fields and validation rules in `init()`. If the form implements `submit()`, the returned values are used as submitted data. See [Aura.Input self-initializing forms](https://github.com/auraphp/Aura.Input/blob/1.x/README.md#self-initializing-forms) for the underlying form API.
```php
use Ray\WebFormModule\AbstractForm;
use Ray\WebFormModule\SetAntiCsrfTrait;
class MyForm extends AbstractForm
{
use SetAntiCsrfTrait;
public function init()
{
$this->setField('name', 'text')
->setAttribs([
'id' => 'name'
]);
$this->filter->validate('name')->is('alnum');
$this->filter->useFieldMessage('name', 'Name must be alphanumeric only.');
}
public function submit()
{
return $_POST;
}
public function __toString()
{
$form = $this->form();
$form .= $this->helper->tag('div', ['class' => 'form-group']);
$form .= $this->helper->tag('label', ['for' => 'name']);
$form .= 'Name:';
$form .= $this->helper->tag('/label') . PHP_EOL;
$form .= $this->input('name');
$form .= $this->error('name');
$form .= $this->helper->tag('/div') . PHP_EOL;
$form .= $this->input('submit');
$form .= $this->helper->tag('/form');
return $form;
}
}
```
## Controller
Annotate methods that require form validation with `#[FormValidation]`. The `form` argument names the form property on the controller, and `onFailure` names the method called when validation fails.
```php
use Ray\Di\Di\Inject;
use Ray\Di\Di\Named;
use Ray\WebFormModule\Annotation\FormValidation;
use Ray\WebFormModule\FormInterface;
class MyController
{
/** @var FormInterface */
protected $contactForm;
#[Inject]
public function setForm(#[Named("contact_form")] FormInterface $form)
{
$this->contactForm = $form;
}
#[FormValidation(form: "contactForm", onFailure: "badRequestAction")]
public function createAction()
{
// validation success
// More detail for vnd.error+json can be added with #[VndError].
}
public function badRequestAction()
{
// validation failed
}
}
```
## View
When the form provides string rendering, echoing the form renders the complete HTML.
```php
echo $form;
```
You can also render individual inputs and errors.
```php
echo $form->input('name'); //
echo $form->error('name'); // "Name must be alphanumeric only." or blank.
```
## CSRF Protections
CSRF protection is **opt-in** and can be enabled through either of two independent paths:
- **Per-form**: add `use SetAntiCsrfTrait;` to the form. `AntiCsrfInterface` is injected at construction time, the token field is added in `postConstruct()`, and every `apply()` call verifies the token.
- **Per-action**: annotate the validated method with `#[CsrfProtection]`. `AuraInputInterceptor` then injects `AntiCsrfInterface` into the form before `apply()` runs.
Either path causes `AbstractForm::apply()` to throw `CsrfViolationException` on token mismatch. Without either path, no CSRF check is performed.
```php
use Ray\WebFormModule\AbstractForm;
use Ray\WebFormModule\Annotation\CsrfProtection;
use Ray\WebFormModule\Annotation\FormValidation;
use Ray\WebFormModule\SetAntiCsrfTrait;
class MyForm extends AbstractForm
{
use SetAntiCsrfTrait;
}
class MyController
{
#[FormValidation(form: "contactForm")]
#[CsrfProtection]
public function createAction()
{
}
}
```
You can provide a custom `AntiCsrf` class. See [Applying CSRF Protections](https://github.com/auraphp/Aura.Input#applying-csrf-protections) in Aura.Input for details.
## Migration From 0.x
Version 1.0 drops Doctrine Annotations in favor of native PHP 8 attributes and tightens type declarations. The most common rewrites are:
| Before (0.x) | After (1.0) |
|--------------------------------------------------------------------|---------------------------------------------------------|
| `@FormValidation(form="f", onFailure="badRequest")` | `#[FormValidation(form: 'f', onFailure: 'badRequest')]` |
| `@FormValidation(form="f", antiCsrf=true)` | `#[FormValidation(form: 'f')]` + `#[CsrfProtection]` |
| `@InputValidation(form="f")` | `#[InputValidation(form: 'f')]` |
| `@VndError(message="...", logref="...")` | `#[VndError(message: '...', logref: '...')]` |
| `new AuraInputInterceptor($injector, $reader)` | `new AuraInputInterceptor($injector)` |
| `public function input($input)` / `public function error($input)` | `input(string $input): string` / `error(string $input): string` |
See [CHANGELOG.md](https://github.com/ray-di/Ray.WebFormModule/blob/1.x/CHANGELOG.md) for the full list of breaking changes.
### Automated Migration With Claude Code
Ray.WebFormModule ships a Claude Code skill at [`.claude/skills/migrate-to-1.0/SKILL.md`](https://github.com/ray-di/Ray.WebFormModule/blob/1.x/.claude/skills/migrate-to-1.0/SKILL.md) that walks an AI assistant through the rewrites above: annotations to attributes, `antiCsrf=true` split into `#[CsrfProtection]`, `Reader` argument removal, and `FormInterface` signature updates. Copy that directory into your consuming project's `.claude/skills/` and invoke it with `/migrate-to-1.0`.
## Validation Exception
`#[InputValidation]` throws `Ray\WebFormModule\Exception\ValidationException` when validation fails. This is useful for API applications where the HTML representation is not used.
```php
use Ray\WebFormModule\Annotation\InputValidation;
class Foo
{
#[InputValidation(form: "form1")]
public function createAction($name)
{
// ...
}
}
```
Installing `Ray\WebFormModule\FormVndErrorModule` makes methods annotated with `#[FormValidation]` throw the same validation exception on failure.
```php
use Ray\Di\AbstractModule;
use Ray\WebFormModule\FormVndErrorModule;
use Ray\WebFormModule\WebFormModule;
class FakeVndErrorModule extends AbstractModule
{
protected function configure()
{
$this->install(new WebFormModule());
$this->override(new FormVndErrorModule());
}
}
```
Echo the caught exception's `error` property to get an [application/vnd.error+json](https://tools.ietf.org/html/rfc6906) representation.
```php
echo $e->error;
//{
// "message": "Validation failed",
// "path": "/path/to/error",
// "validation_messages": {
// "name": [
// "Name must be alphanumeric only."
// ]
// }
//}
```
Add more detail to `vnd.error+json` with the `#[VndError]` attribute.
```php
#[FormValidation(form: "contactForm")]
#[VndError(message: "foo validation failed", logref: "a1000", path: "/path/to/error", href: ["_self" => "/path/to/error", "help" => "/path/to/help"])]
public function createAction()
{
}
```
## Demo
Run the demo application from the Ray.WebFormModule repository.
```bash
php -S docs/demo/1.csrf/web.php
```
# Validation
* You can define resource APIs in the JSON schema.
* You can separate the validation code with `#[Valid]`, `#[OnValidate]` attribute.
* Please see the form for validation by web form.
# JSON Schema
The [JSON Schema](http://json-schema.org/) is the standard for describing and validating JSON objects. `@JsonSchema` and the resource body returned by the method of annotated resource class are validated by JSON schema.
### Install
If you want to validate in all contexts including production, create `AppModule`, if validation is done only during development, create `DevModule` and install within it
```php?start_inline
use BEAR\Resource\Module\JsonSchemaModule; // Add this line
use BEAR\Package\AbstractAppModule;
class AppModule extends AbstractAppModule
{
protected function configure()
{
// ...
$this->install(
new JsonSchemaModule(
$appDir . '/var/json_schema',
$appDir . '/var/json_validate'
)
); // Add this line
}
}
```
Create directories for the JSON schema files
```bash
mkdir var/json_schema
mkdir var/json_validate
```
In the `var/json_schema/`, store the JSON schema file which is the specification of the body of the resource, and the `var/json_validate/` stores the JSON schema file for input validation.
### @JsonSchema annotation
Annotate the method of the resource class by adding `@JsonSchema`, then add the `schema` property by specifying the JSON schema file name, which is `user.json` for this purpose.
### schema
src/Resource/App/User.php
```php?start_inline
use BEAR\Resource\Annotation\JsonSchema; // Add this line
class User extends ResourceObject
{
#[JsonSchema('user.json')]
public function onGet(): static
{
$this->body = [
'firstName' => 'mucha',
'lastName' => 'alfons',
'age' => 12
];
return $this;
}
}
```
We will create a JSON schema named `/var/json_schema/user.json`
```json
{
"type": "object",
"properties": {
"firstName": {
"type": "string",
"maxLength": 30,
"pattern": "[a-z\\d~+-]+"
},
"lastName": {
"type": "string",
"maxLength": 30,
"pattern": "[a-z\\d~+-]+"
}
},
"required": ["firstName", "lastName"]
}
```
### key
If the body has an index key, specify it with the key property of the annotation
```php?start_inline
use BEAR\Resource\Annotation\JsonSchema; // Add this line
class User extends ResourceObject
{
#[JsonSchema(key:'user', schema:'user.json')]
public function onGet()
{
$this->body = [
'user' => [
'firstName' => 'mucha',
'lastName' => 'alfons',
'age' => 12
]
];
return $this;
}
}
```
### params
The `params` property specifies the JSON schema file name for the argument validation
```php?start_inline
use BEAR\Resource\Annotation\JsonSchema; // Add this line
class Todo extends ResourceObject
{
#[JsonSchema(key:'user', schema:'user.json', params:'todo.post.json')]
public function onPost(string $title)
```
We place the JSON schema file
**/var/json_validate/todo.post.json**
```json
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "/todo POST request validation",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 40
}
}
```
By constantly verifying in a standardized way instead of proprietary documentation, the specification is **reliable and understandable** to both humans and machines.
### target
To apply schema validation to the representation of the resource object (the rendered result) rather than to the body of the ResourceObject, specify the option `target='view'`.
```php
#[JsonSchema(schema: 'user.json', target: 'view')]
```
### Related Links
* [Example](http://json-schema.org/examples.html)
* [Understanding JSON Schema](https://spacetelescope.github.io/understanding-json-schema/)
* [JSON Schema Generator](https://jsonschema.net/#/editor)
## Exception Handling
When JSON Schema validation fails, BEAR.Resource (1.33.0+) throws a typed exception that tells you whether the problem was in the **request** (client error) or the **response** (server bug):
| Exception | HTTP | Meaning |
|-----------|------|---------|
| `JsonSchemaRequestException` | 400 | Input params failed schema validation |
| `JsonSchemaResponseException` | 500 | Response body failed schema validation |
Both extend `JsonSchemaException`, so you can catch either specifically or together.
### Accessing Structured Errors
`$e->getErrors()` returns a `JsonSchemaErrors` collection:
```php
use BEAR\Resource\Exception\JsonSchemaRequestException;
use BEAR\Resource\Exception\JsonSchemaResponseException;
try {
$response = $resource->post('app://self/user', $params);
} catch (JsonSchemaRequestException $e) {
$errors = $e->getErrors(); // JsonSchemaErrors
$errors->count(); // number of violations
$errors->first(); // first JsonSchemaError or null
// Iterate over each error
foreach ($errors as $error) {
echo $error->property; // e.g. "email"
echo $error->message; // human-readable message
}
// Group by field — useful for building API error responses
$byField = $errors->byProperty(); // array
## Tag-based Cache Invalidation
Content caching has dependency issues. If content A depends on content B, and B depends on C, then when C is updated, not only must C's cache and ETag be updated, but also B's cache and ETag (which depends on C), and A's cache and ETag (which depends on B).
BEAR.Sunday solves this problem by having each resource hold the URI of dependent resources as tags. When a resource embedded with `#[Embed]` is modified, the cache and ETag of all related resources are invalidated, and cache regeneration occurs for the next request.
## Donut Cache
Donut caching is a partial caching technique for cache optimization. It separates content into cacheable and non-cacheable parts and combines them for output.
For example, consider content containing a non-cacheable resource like "`Welcome to $name`". The non-cacheable (do-not-cache) part is combined with other cacheable parts for output.
In this case, since the entire content is dynamic, the whole donut is not cached. Therefore, no ETag is output either.
## Donut Hole Cache
When the donut hole part is cacheable, it can be handled the same way as donut cache. In the example above, a weather forecast resource that changes once per hour is cached and included in the news resource.
In this case, since the donut content as a whole (news) is static, the entire content is also cached and given an ETag. This creates cache dependency. When the donut hole content is updated, the entire cached donut needs to be regenerated.
This dependency resolution happens automatically. To minimize computational resources, the donut part computation is reused. When the hole part (weather resource) is updated, the cache and ETag of the entire content are also automatically updated.
### Recursive Donut
The donut structure is applied recursively. For example, if A contains B and B contains C, when C is modified, A's cache and B's cache are reused except for the modified C part. A's and B's caches and ETags are regenerated, but database access for A and B content retrieval and view rendering are not performed.
The optimized partial cache structure performs content regeneration with minimal cost. Clients don't need to know about the content cache structure.
## Event-Driven Content
Traditionally, CDNs considered content requiring application logic as "dynamic" and therefore not cacheable by CDNs. However, some CDNs like Fastly and Akamai now support immediate or tag-based cache invalidation within seconds, making [this thinking obsolete](https://www.fastly.com/blog/leveraging-your-cdn-cache-uncacheable-content).
BEAR.Sunday dependency resolution works not only server-side but also on shared caches. When AOP detects changes and makes PURGE requests to shared caches, related cache invalidation occurs on shared caches just like server-side.
## Conditional Requests
Content changes are managed by AOP, and content entity tags (ETags) are automatically updated. HTTP conditional requests using ETags not only minimize computational resource usage, but responses returning only `304 Not Modified` also minimize network resource usage.
# Usage
For classes to be cached, use the `#[DonutCache]` attribute for donut cache (when embedded content is not cacheable), and `#[CacheableResponse]` for other cases:
```php
use BEAR\RepositoryModule\Annotation\CacheableResponse;
#[CacheableResponse]
class BlogPosting extends ResourceObject
{
public $headers = [
RequestHeader::CACHE_CONTROL => CacheControl::NO_CACHE
];
#[Embed(rel: "comment", src: "page://self/html/comment")]
public function onGet(int $id = 0): static
{
$this->body['article'] = 'hello world';
return $this;
}
public function onDelete(int $id = 0): static
{
return $this;
}
}
```
### recursive donut
The donut structure will be recursively applied.
For example, if A contains B and B contains C and C is modified, A's cache and B's cache will be reused except for the modified C. A's and B's caches and ETags will be regenerated, but DB access to retrieve A's and B's content and rendering of views will not be done.
The optimized structure of the partial cache performs content regeneration with minimal cost. The client does not need to know about the content cache structure.
## Event-driven content
Traditionally, CDNs have believed that content that requires application logic is "dynamic" and therefore cannot be cached by a CDN. However, some CDNs, such as Fastly and Akamai, allow immediate or tag-based cache invalidation within seconds, [this idea is a thing of the past](https://www.fastly.com/blog/leveraging-your-cdn-cache- uncacheable-content).
Sunday dependency resolution is done not only on the server side, but also on the shared cache; when AOP detects a change and makes a PURGE request to the shared cache, the related cache on the shared cache will be invalidated, just like on the server side.
## Conditional request
Content changes are managed by AOP, and the entity tag (ETag) of the content is automatically updated. conditional requests for HTTP using ETag not only minimize the use of computational resources, but responses that only return `304 Not Modified` also minimize the use of network resources. Conditional HTTP requests using ETag not only minimize the use of computational resources, but also minimize the use of network resources by simply returning `304 Not Modified`.
# Usage
Give the class to be cached the attribute `#[DonutCache]` if it is a donut cache (embedded content is not cacheable) and `#[CacheableResponse]` otherwise.
```php
class Todo extends ResourceObject
{
#[CacheableResponse]
public function onPut(int $id = 0, string $todo): static
{
}
#[RefreshCache]
public function onDelete(int $id = 0): static
{
}
}
```
If you give attributes in either way, all the features introduced in the overview will apply.
Caching is not disabled by time (TTL) by default, assuming event-driven content
Note that with `#[DonutCache]` the whole content will not be cached, but with `#[CacheableResponse]` it will be.
## TTL
TTL is specified with `DonutRepositoryInterface::put()`.
`ttl` is the cache time for non-donut holes, `sMaxAge` is the cache time for CDNs.
```php
use BEAR\RepositoryModule\Annotation\CacheableResponse;
#[CacheableResponse]
class BlogPosting extends ResourceObject
{
public function __construct(private DonutRepositoryInterface $repository)
{}
#[Embed(rel: "comment", src: "page://self/html/comment")]
public function onGet(): static
{
// process ...
$this->repository->put($this, ttl:10, sMaxAge:100);
return $this;
}
}
```
### Default TTL value
For event-driven content, changes to the content must be reflected immediately in the cache, so the default TTL varies depending on the CDN module installed. Therefore, the default TTL will vary depending on the CDN module installed: indefinitely (1 year) if the CDN supports tag-based disabling of caching, or 10 seconds if it does not.
The expected cache reflection time is immediate for Fastly, a few seconds for Akamai, and 10 seconds for others.
To customize it, bind it by implementing `CdnCacheControlHeaderSetterInterface` with reference to `CdnCacheControlHeader`.
## Cache invalidation
Use the methods of `DonutRepositoryInterface` to manually invalidate the cache.
This will invalidate not only the specified cache, but also the cache of the ETag, any other resources it depends on, and the cache of the ETag on the server side and, if possible, on the CDN.
```php
interface DonutRepositoryInterface
{
public function purge(AbstractUri $uri): void;
public function invalidateTags(array $tags): void;
}
```
### Invalidate by URI
```php
// example
$this->repository->purge(new Uri('app://self/blog/comment'));
```
### Disable by tag
```php
$this->repository->invalidateTags(['template_a', 'campaign_b']);
```
### Tag Invalidation in CDN
In order to enable tag-based cache invalidation in CDN, you need to implement and bind `PurgerInterface`.
```php
use BEAR\QueryRepository\PurgerInterface;
interface PurgerInterface
{
public function __invoke(string $tag): void;
}
```
### Specify dependent tags.
Use the `SURROGATE_KEY` header to specify the key for PURGE. Use a space as a separator for multiple strings.
```php
use BEAR\QueryRepository\Header;
class Foo
{
public $headers = [
Header::SURROGATE_KEY => 'template_a campaign_b'
];
```
If the cache is invalidated by `template_a` or `campaign_b` tags, Foo's cache and Foo's ETag will be invalidated both server-side and CDN.
### Resource Dependencies.
Use `UriTagInterface` to convert a URI into a dependency tag string.
```php
public function __construct(private UriTagInterface $uriTag)
{}
```
```php
$this->headers[Header::SURROGATE_KEY] = ($this->uriTag)(new Uri('app://self/foo'));
```
This cache will be invalidated both server-side and CDN when `app://self/foo` is modified.
### Make associative array a resource dependency.
```php
// bodyの内容
[
['id' => '1', 'name' => 'a'],
['id' => '2', 'name' => 'b'],
]
```
If you want to generate a list of dependent URI tags from a `body` associative array like the above, you can specify the URI template with the `fromAssoc()` method.
```php
$this->headers[Header::SURROGATE_KEY] = $this->uriTag->fromAssoc(
uriTemplate: 'app://self/item{?id}',
assoc: $this->body
);
```
In the above case, this cache will be invalidated for both server-side and CDN when `app://self/item?id=1` and `app://self/item?id=2` are changed.
## Configuration
### Redis Marshaller
The Redis cache adapter allows you to configure data compression and serialization methods.
A marshaller handles the serialization of PHP objects and arrays when storing them in Redis, and deserialization when retrieving them.
```php
use BEAR\QueryRepository\StorageRedisDsnModule;
$this->install(
new StorageRedisDsnModule(
dsn: 'redis://localhost:6379',
marshallingOptions: [
'enabled' => true,
'type' => 'deflate', // 'default' or 'deflate'
'use_igbinary' => true // requires ext-igbinary
]
)
);
```
**Marshaller types:**
- `default`: Uses PHP's standard serialization (enabling `use_igbinary` uses a more efficient binary format)
- `deflate`: Compresses data before storing (uses zlib)
Use `deflate` if you want to reduce Redis memory usage. This is a trade-off with CPU usage.
## CDN
If you install a module that supports a specific CDN, vendor-specific headers will be output.
```php
$this->install(new FastlyModule())
$this->install(new AkamaiModule())
```
## Multi-CDN
You can also configure a multi-tier CDN and set the TTL according to the role. For example, in this diagram, a multi-functional CDN is placed upstream, and a conventional CDN is placed downstream. Content invalidation is done for the upstream CDN, and the downstream CDN uses it.
# Response headers
Sunday will automatically do the cache control for the CDN and output the header for the CDN. Client cache control is described in `$header` of ResourceObject depending on the content.
This section is important for security and maintenance purposes.
Make sure to specify the `Cache-Control` in all ResourceObjects.
### Cannot cache
Always specify content that cannot be cached.
```php
ResponseHeader::CACHE_CONTROL => CacheControl::NO_STORE
```
### Conditional requests
Check the server for content changes before using the cache. Server-side content changes will be detected and reflected.
```php
ResponseHeader::CACHE_CONTROL => CacheControl::NO_CACHE
```
### Specify client cache time.
The client is cached on the client. This is the most efficient cache, but server-side content changes will not be reflected at the specified time.
Also, this cache is not used when the browser reloads. The cache is used when a transition is made with the `` tag or when a URL is entered.
```php
ResponseHeader::CACHE_CONTROL => 'max-age=60'
```
If response time is important to you, consider specifying SWR.
```php
ResponseHeader::CACHE_CONTROL => 'max-age=30 stale-while-revalidate=10'
```
In this case, when the max-age of 30 seconds is exceeded, the old cached (stale) response will be returned for up to 10 seconds, as specified in the SWR, until a fresh response is obtained from the origin server. This means that the cache will be updated sometime between 30 and 40 seconds after the last cache update, but every request will be a response from the cache and will be fast.
#### RFC7234 compliant clients
To use the client cache with APIs, use an RFC7234 compliant API client.
* iOS [NSURLCache](https://nshipster.com/nsurlcache/)
* Android [HttpResponseCache](https://developer.android.com/reference/android/net/http/HttpResponseCache)
* PHP [guzzle-cache-middleware](https://github.com/Kevinrob/guzzle-cache-middleware)
* JavaScript(Node) [cacheable-request](https://www.npmjs.com/package/cacheable-request)
* Go [lox/httpcache](https://github.com/lox/httpcache)
* Ruby [faraday-http-cache](https://github.com/plataformatec/faraday-http-cache)
* Python [requests-cache](https://pypi.org/project/requests-cache/)
### private
Specify `private` if you do not want to share the cache with other clients. The cache will be saved only on the client side. In this case, do not specify the cache on the server side.
````php
ResponseHeader::CACHE_CONTROL => 'private, max-age=30'
````
> Even if you use shared cache, you don't need to specify `public` in most cases.
## Cache design
APIs (or content) can be divided into two categories: **Information APIs** (Information APIs) and **Computation APIs** (Computation APIs). The **Computation API** is content that is difficult to reproduce and is truly dynamic, making it unsuitable for caching. The Information API, on the other hand, is an API for content that is essentially static, even if it is read from a DB and processed by PHP.
It analyzes the content in order to apply the appropriate cache.
* Information API or Computation API?
* Dependencies are
* Are the comprehension relationships
* Is the invalidation triggered by an event or TTL?
* Is the event detectable by the application or does it need to be monitored?
* Is the TTL predictable or unpredictable?
Consider making cache design a part of the application design process and make it a specification. It should also contribute to the safety of your project throughout its lifecycle.
### Adaptive TTL
Adaptive TTL is the ability to predict the lifetime of content and correctly tell the client or CDN when it will not be updated by an event during that time. For example, when dealing with a stock API, if it is Friday night, we know that the information will not be updated until the start of trading on Monday. We calculate the number of seconds until that time, specify it as the TTL, and then specify the appropriate TTL when it is time to trade.
The client does not need to request a resource that it knows will not be updated.
## #[Cacheable].
The traditional ##[Cacheable] TTL caching is also supported.
Example: 30 seconds cache on the server side, 30 seconds cache on the client.
The same number of seconds will be cached on the client side since it is specified on the server side.
The same number of seconds will be cached on the client side.
use BEAR\RepositoryModule\Annotation\Cacheable;
#[Cacheable(expirySecond: 30)]]
class CachedResource extends ResourceObject
{
````
Example: Cache the resource on the server and client until the specified expiration date (the date in `$body['expiry_at']`)
```php?start_inline
use BEAR\RepositoryModule\Annotation\Cacheable;
#[Cacheable(expiryAt: 'expiry_at')]]
class CachedResource extends ResourceObject
{
```.
See the [HTTP Cache](https://bearsunday.github.io/manuals/1.0/ja/http-cache.html) page for more information.
## Conclusion
Web content can be of the information (data) type or the computation (process) type. Although the former is essentially static, it is difficult to treat it as completely static content due to the problems of managing content changes and dependencies, so the cache was invalidated by TTL even though no content changes occurred. Sunday's caching framework treats information type content as static as possible, maximizing the power of the cache.
## Terminology
* [条件付きリクエスト](https://developer.mozilla.org/ja/docs/Web/HTTP/Conditional_requests)
* [ETag (バージョン識別子)](https://developer.mozilla.org/ja/docs/Web/HTTP/Headers/ETag)
* [イベントドリブン型コンテンツ](https://www.fastly.com/blog/rise-event-driven-content-or-how-cache-more-edge)
* [ドーナッツキャッシュ / 部分キャッシュ](https://www.infoq.com/jp/news/2011/12/MvcDonutCaching/)
* [サロゲートキー / タグベースの無効化](https://docs.fastly.com/ja/guides/getting-started-with-surrogate-keys)
* ヘッダー
* [Cache-Control](https://developer.mozilla.org/ja/docs/Web/HTTP/Headers/Cache-Control)
* [CDN-Cache-Control](https://blog.cloudflare.com/cdn-cache-control/)
* [Vary](https://developer.mozilla.org/ja/docs/Web/HTTP/Headers/Vary)
* [Stale-While-Revalidate (SWR)](https://www.infoq.com/jp/news/2020/12/ux-stale-while-revalidate/)
# Stream Response
Normally, resources are rendered by renderers into one string and finally `echo`ed out, but then you cannot output content whose size exceeds the memory limit of PHP. With `StreamRenderer` you can stream HTTP output and you can output large size content while keeping memory consumption low. Stream output can also be used in coexistence with existing renderers.
## Change Transferer and Renderer
Use the [StreamTransferInject](https://github.com/bearsunday/BEAR.Streamer/blob/1.x/src/StreamTransferInject.php) trait on the page to render and respond to the stream output. In the example of this download page, since `$body` is made to be a resource variable of the stream, the injected renderer is ignored and the resource is streamed.
```php?start_inline
use BEAR\Streamer\StreamTransferInject;
class Download extends ResourceObject
{
use StreamTransferInject;
public $headers = [
'Content-Type' => 'image/jpeg',
'Content-Disposition' => 'attachment; filename="image.jpg"'
];
public function onGet(): static
{
$fp = fopen(__DIR__ . '/BEAR.jpg', 'r');
$this->body = $fp;
return $this;
}
}
```
## With Renderers
Stream output can coexist with conventional renderers. Normally, Twig renderers and JSON renderers generate character strings, but when a stream is assigned to a part of it, the whole is output as a stream.
This is an example of assigning a `string` and a `resource` variable to the Twig template and generating a page of inline image.
Template
```twig
Hello, {% raw %}{{ name }}{% endraw %}
```
`name` assigns the string as usual, but assigns the resource variable of the image file's pointer resource to` image` with the `base64-encode` filter.
```php?start_inline
class Image extends ResourceObject
{
use StreamTransferInject;
public function onGet(string $name = 'inline image'): static
{
$fp = fopen(__DIR__ . '/image.jpg', 'r');
stream_filter_append($fp, 'convert.base64-encode'); // image base64 format
$this->body = [
'name' => $name,
'image' => $fp
];
return $this;
}
}
```
If you want to further control streaming such as streaming bandwidth and timing control, uploading to the cloud, etc use [StreamResponder](https://github.com/bearsunday/BEAR.Streamer/blob/1.x/src /StreamResponder.php ) which is build for it.
The demo is available at [MyVendor.Stream](https://github.com/bearsunday/MyVendor.Stream).
---
*[This document](https://github.com/bearsunday/bearsunday.github.io/blob/master/manuals/1.0/en/stream.md) needs to be proofread by native speaker.*
# Parallel Resource Execution Alpha
BEAR.Async turns the previously sequential fetch of `#[Embed]` resources into transparent parallel execution. Without touching your resource code, just add a dedicated entrypoint script for parallel execution and embedded resources automatically switch to parallel fetching.
## Overview
In standard BEAR.Sunday, `#[Embed]` resources are fetched sequentially. With BEAR.Async and a runtime selected, they are fetched in parallel.
```text
[Sequential] [Parallel]
Request Request
│ │
├── Embed 1 ──── 50ms ├── Embed 1 ──┬── 50ms
├── Embed 2 ──── 50ms ├── Embed 2 ──┤
├── Embed 3 ──── 50ms ├── Embed 3 ──┤
└── Embed 4 ──── 50ms └── Embed 4 ──┘
│ │
Response (200ms) Response (50ms)
```
## Installation
```bash
composer require bear/async
```
## Runtime environments
Choose a runtime that matches your server setup.
| Use case | Entrypoint | Runtime setup |
|---|---|---|
| PHP-FPM / Apache (with embedded resources) | `bin/async.php` | the library `bootstrap.php` overlays the parallel runtime on `AppModule` |
| Swoole HTTP Server | `bin/swoole.php` | install `AsyncSwooleModule` in `AppModule` |
### Parallel execution (ext-parallel)
A runtime for typical web applications running on PHP-FPM / Apache. It executes `#[Embed]` in parallel using an ext-parallel thread pool.
Add `bin/async.php` next to `bin/app.php`. This entrypoint delegates to the library `bootstrap.php`, which overlays the ext-parallel runtime on top of the normal `AppModule`.
```text
bin/async.php → vendor/bear/async/bootstrap.php → AppModule + parallel runtime
```
```php
install(new AsyncSwooleModule());
$this->install(new PdoPoolEnvModule('PDO_DSN', 'PDO_USER', 'PDO_PASSWORD'));
}
}
```
In Swoole, coroutines share memory, so a connection pool via `PdoPoolEnvModule` is required. In read-heavy setups that make heavy use of embedded resources, the pool size should account not only for the number of incoming HTTP requests but also for the number of embeds executed concurrently within one request. To avoid queueing, use `PDO_POOL_SIZE >= embed_count * request_concurrency` as a starting point; intentionally use a smaller pool when you want to cap concurrent connections to the database.
> **Technical note (pool connection acquisition):** Connection acquisition from the pool is managed per coroutine. Even when both `PDO` and `ExtendedPdo` are injected within the same coroutine, they share a single connection and that connection is returned to the pool exactly once via `Coroutine::defer()` when the coroutine ends. This prevents a single piece of work from unintentionally holding two connections. Furthermore, requests embedded via `#[Embed]` are lazily evaluated, so the pool is not touched at the point the embed is declared with `#[Embed]`; connection acquisition is deferred until each request is actually executed.
>
> **Technical note (PDOProxy handling):** Swoole wraps `PDO` in its own `PDOProxy` for coroutine support, but BEAR.Async absorbs this wrapping internally so the value can be treated as a regular `PDO`. If the original `PDO` cannot be extracted for some reason, the reflection failure is not propagated as-is; instead it is surfaced as a domain-specific PDO proxy extraction exception.
Swoole coroutines and an active Xdebug do not run safely together. Run Swoole entrypoints with a PHP that does not load Xdebug, or set `XDEBUG_MODE=off` for local verification.
## Usage
Once a runtime is selected, existing `#[Embed]` resources are automatically executed in parallel.
```php
class Dashboard extends ResourceObject
{
#[Embed(rel: 'user', src: '/user{?id}')]
#[Embed(rel: 'notifications', src: '/notifications{?user_id}')]
#[Embed(rel: 'stats', src: '/stats{?user_id}')]
public function onGet(string $id): static
{
$this->body['id'] = $id;
return $this;
}
}
```
In development, run synchronously via `bin/app.php` for debugging; in production, switch to parallel execution by starting from `bin/async.php`.
## Why no code change is needed
In BEAR.Sunday, information is **structured** as resources identified by URIs. `#[Embed]` does not embed the result of a resource — it embeds the resource request itself and declares a relationship between resources. Choosing the execution strategy — sequential, ext-parallel workers, or Swoole coroutines — is the Linker's job; resource classes do not need to know whether they were called synchronously or in parallel.
In the default mode these requests are resolved one by one at rendering time. In parallel mode, the moment the first embedded request is resolved, the remaining embedded requests are executed together in parallel. BEAR.Async asynchronous requests share the same type as ordinary BEAR.Resource requests, so the HAL renderer and other surrounding machinery can integrate them into serialization without being aware of the difference.
The "function coloring" problem often raised in async programming — a function calling an async function must itself be async, contaminating the whole codebase — is cut off at the resource boundary. The code is the same under sync and parallel execution; only the execution strategy changes.
This is not specific to BEAR.Async; it is a property of BEAR.Sunday as a whole. Where MVC frameworks write *how to execute* procedurally, BEAR.Sunday expresses *relationships between resources* declaratively. Because the declaration is independent of the execution strategy, swapping strategies has no effect on the code.
## Demo and benchmarks
The BEAR.Async repository includes a Docker-based demo and benchmark scripts that compare Sync, ext-parallel, and Swoole behavior. See the [demo guide](https://github.com/bearsunday/BEAR.Async/tree/1.x/demo) and [benchmark results](https://github.com/bearsunday/BEAR.Async/blob/1.x/docs/benchmark-results.md) for details.
## Requirements
Each runtime requires the corresponding PHP extension.
| Runtime | Requires | Application-side change |
|---|---|---|
| ext-parallel | ZTS PHP + ext-parallel | add `bin/async.php` |
| ext-swoole | ext-swoole | install `AsyncSwooleModule`, use `bin/swoole.php` |
## SQL resources with BDR + `#[Embed]`
To run multiple SQL queries for one page, split each query into its own `ResourceObject` and let `#[Embed]` parallelize them via AsyncLinker. The call site just composes resources — the runtime decides how to execute the embeds in parallel.
Combined with Ray.MediaQuery's [BDR pattern](https://github.com/ray-di/Ray.MediaQuery/blob/1.x/BDR_PATTERN.md) (`#[DbQuery]` interface + factory + immutable domain object), SQL stays in `var/sql/*.sql`, the call site reads as plain objects, and the resource graph itself is what gets parallelized.
Recipe dependency (not bundled with BEAR.Async):
```bash
composer require ray/media-query
```
```php
use BEAR\Resource\Annotation\Embed;
use BEAR\Resource\ResourceObject;
use Ray\MediaQuery\Annotation\DbQuery;
// Domain object — immutable snapshot
final class UserAccount
{
public function __construct(
public readonly int $id,
public readonly string $name,
) {
}
}
// Repository — SQL lives in var/sql/user.sql.
// UserFactory hydrates the row into UserAccount; see BDR_PATTERN.md for factory details.
interface UserRepositoryInterface
{
#[DbQuery('user', factory: UserFactory::class)]
public function getUser(int $id): UserAccount;
}
// Resource — one resource per SQL
class User extends ResourceObject
{
public function __construct(private UserRepositoryInterface $repo)
{
}
public function onGet(int $id): static
{
$this->body = ['user' => $this->repo->getUser($id)];
return $this;
}
}
// Aggregate — Embeds parallelize automatically under AsyncLinker
class UserDashboard extends ResourceObject
{
#[Embed(rel: 'user', src: 'app://self/user{?id}')]
#[Embed(rel: 'posts', src: 'app://self/user/posts{?id}')]
#[Embed(rel: 'comments', src: 'app://self/user/comments{?id}')]
public function onGet(int $id): static
{
return $this;
}
}
```
- SQL stays in `var/sql/*.sql` (Ray.MediaQuery convention)
- Domain objects are immutable snapshots; no `$results['user'][0] ?? null` plumbing at the call site
- AsyncLinker runs the three embeds in parallel via ext-parallel (PHP-FPM / Apache) or Swoole coroutines
- Without ext-parallel and without Swoole the same code runs synchronously per request, which is fine for PHP-FPM (each request is its own process)
- For Swoole, install `PdoPoolEnvModule` so each coroutine borrows a pooled PDO connection
## References
- [BEAR.Async](https://github.com/bearsunday/BEAR.Async)
- [BEAR.Async Demo Guide](https://github.com/bearsunday/BEAR.Async/tree/1.x/demo)
- [BEAR.Async Benchmark Results](https://github.com/bearsunday/BEAR.Async/blob/1.x/docs/benchmark-results.md)
- [Ray.MediaQuery BDR Pattern](https://github.com/ray-di/Ray.MediaQuery/blob/1.x/BDR_PATTERN.md)
- [Parallel Execution Architecture](https://bearsunday.github.io/BEAR.Async/parallel-execution-architecture.html)
# High-Performance Servers
BEAR.Sunday applications can run on high-performance PHP servers that eliminate per-request bootstrap overhead. This guide covers three server options: Swoole, RoadRunner, and FrankenPHP.
## Overview
In traditional PHP-FPM, each request bootstraps the entire application:
```text
Request -> Boot Framework -> Route -> Execute -> Response -> Shutdown
Request -> Boot Framework -> Route -> Execute -> Response -> Shutdown
Request -> Boot Framework -> Route -> Execute -> Response -> Shutdown
```
With persistent worker mode, the application boots once:
```text
Boot Framework (once)
|
Request -> Route -> Execute -> Response
Request -> Route -> Execute -> Response
Request -> Route -> Execute -> Response
```
This eliminates boot overhead, resulting in significantly lower latency and higher throughput.
BEAR.Sunday's stateless resource design and immutable architecture are well-suited for persistent worker environments, enabling seamless transition to worker mode without global state issues.
## Server Comparison
| Feature | Swoole | RoadRunner | FrankenPHP |
|---------|--------|------------|------------|
| Language | C + PHP | Go + PHP | Go + PHP |
| Worker Mode | Yes | Yes | Yes |
| HTTP/2 | Yes | Yes | Yes |
| HTTP/3 | No | No | Yes |
| WebSocket | Native | Native | Via Caddy |
| Coroutines | Yes | No | No |
| Hot Reload | Manual | Yes | Yes |
| Memory Limit | Shared | Per worker | Per worker |
## Quick Start with Docker
The [bear-sunday-servers](https://github.com/bearsunday/bear-sunday-servers) repository provides ready-to-use Docker configurations for all three servers.
```bash
git clone https://github.com/bearsunday/bear-sunday-servers.git
cd bear-sunday-servers
# Swoole (port 8081)
cd swoole && docker compose up -d && curl http://localhost:8081/
# RoadRunner (port 8082)
cd roadrunner && docker compose up -d && curl http://localhost:8082/
# FrankenPHP (port 8080)
cd frankenphp && docker compose up -d && curl http://localhost:8080/
```
---
## Swoole
[Swoole](https://www.swoole.com/) is a coroutine-based PHP extension providing event-driven asynchronous I/O.
### Features
- **Event-Driven**: Asynchronous I/O handling
- **Coroutines**: Concurrent request processing without threads
- **Request Isolation**: Coroutine-context request isolation
- **High Performance**: Eliminates per-request boot overhead
- **Memory Efficient**: Shared memory between workers
### Install
#### Swoole Extension (ext-swoole ^6.1)
```bash
pecl install swoole
```
Or compile from source:
```bash
git clone https://github.com/swoole/swoole-src.git && \
cd swoole-src && \
phpize && \
./configure && \
make && make install
```
Add `extension=swoole.so` to your `php.ini`.
#### BEAR.Swoole Package
```bash
composer require bear/swoole
```
### Bootstrap Script
Create `bin/swoole.php`:
```php
getInstance(AppInterface::class);
assert($app instanceof App);
// Create RoadRunner worker
$worker = Worker::create();
$factory = new Psr17Factory();
$psr7Worker = new PSR7Worker($worker, $factory, $factory, $factory);
$requestCount = 0;
while ($psrRequest = $psr7Worker->waitRequest()) {
try {
if (! $psrRequest instanceof ServerRequestInterface) {
break;
}
// Convert PSR-7 request to $_SERVER format
$server = createServerVars($psrRequest);
$globals = createGlobals($psrRequest);
// Route and execute request
$request = $app->router->match($globals, $server);
$response = $app->resource->{$request->method}->uri($request->path)($request->query);
assert($response instanceof ResourceObject);
// Convert ResourceObject to PSR-7 Response
$psrResponse = $factory->createResponse($response->code);
foreach ($response->headers as $name => $value) {
$psrResponse = $psrResponse->withHeader($name, $value);
}
$psrResponse = $psrResponse->withBody($factory->createStream((string) $response));
$psr7Worker->respond($psrResponse);
} catch (Throwable $e) {
$psr7Worker->respond($factory->createResponse(500)->withBody(
$factory->createStream($e->getMessage())
));
}
gc_collect_cycles();
$requestCount++;
if ($maxRequests > 0 && $requestCount >= $maxRequests) {
break;
}
}
function createServerVars(ServerRequestInterface $request): array
{
$uri = $request->getUri();
$server = $request->getServerParams();
$server['REQUEST_METHOD'] = $request->getMethod();
$server['REQUEST_URI'] = $uri->getPath() . ($uri->getQuery() ? '?' . $uri->getQuery() : '');
$server['QUERY_STRING'] = $uri->getQuery();
$server['HTTP_HOST'] = $uri->getHost();
foreach ($request->getHeaders() as $name => $values) {
$key = 'HTTP_' . strtoupper(str_replace('-', '_', $name));
$server[$key] = implode(', ', $values);
}
return $server;
}
function createGlobals(ServerRequestInterface $request): array
{
return [
'_GET' => $request->getQueryParams(),
'_POST' => (array) $request->getParsedBody(),
'_COOKIE' => $request->getCookieParams(),
'_FILES' => $request->getUploadedFiles(),
'_SERVER' => createServerVars($request),
];
}
```
### Run
```bash
./rr serve -c .rr.yaml
```
### Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `BEAR_CONTEXT` | prod-hal-app | BEAR.Sunday context |
| `MAX_REQUESTS` | 1000 | Requests before worker restart |
### Architecture
```text
RoadRunner (Go)
|
+-- PHP Worker 1 (persistent)
+-- PHP Worker 2 (persistent)
+-- PHP Worker N (persistent)
```
Each worker boots BEAR.Sunday once and handles requests via pipes.
### Metrics
Prometheus metrics available at `http://localhost:2112/metrics`.
---
## FrankenPHP
[FrankenPHP](https://frankenphp.dev/) is a modern PHP application server built on Caddy with worker mode support.
### Features
- **Worker Mode**: Eliminates application boot cost per request
- **HTTP/2 & HTTP/3**: Automatic HTTPS with Caddy
- **Production Ready**: OPcache JIT, multi-stage builds
- **Development Ready**: Xdebug, hot reload
### Install
FrankenPHP is typically used via Docker. For standalone installation, see [FrankenPHP documentation](https://frankenphp.dev/docs/).
### Worker Script
Create `bin/worker.php`:
```php
getInstance(AppInterface::class);
assert($app instanceof App);
$requestCount = 0;
// FrankenPHP worker loop
// Superglobals ($_GET, $_POST, $_SERVER) are automatically reset
do {
$running = frankenphp_handle_request(static function () use ($app): void {
try {
// Check HTTP cache
if ($app->httpCache->isNotModified($_SERVER)) {
$app->httpCache->transfer();
return;
}
// Route and execute request
$request = $app->router->match($GLOBALS, $_SERVER);
$response = $app->resource->{$request->method}->uri($request->path)($request->query);
assert($response instanceof ResourceObject);
$response->transfer($app->responder, $_SERVER);
} catch (Throwable $e) {
$app->throwableHandler->handle($e, $request ?? null)->transfer();
}
gc_collect_cycles();
});
$requestCount++;
if ($maxRequests > 0 && $requestCount >= $maxRequests) {
break;
}
} while ($running);
```
### Caddyfile Configuration
```caddyfile
{
admin off
frankenphp {
worker /app/bin/worker.php {
num {$FRANKENPHP_NUM_WORKERS:4}
}
}
}
{$SERVER_NAME::8080} {
root * /app/public
encode zstd br gzip
respond /health 200
php_server
log {
output stdout
format console
}
}
```
### Run with Docker
```bash
docker run -v $PWD:/app -p 8080:8080 dunglas/frankenphp
```
### Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `BEAR_CONTEXT` | prod-hal-app | BEAR.Sunday context |
| `MAX_REQUESTS` | 1000 | Requests before worker restart |
| `SERVER_NAME` | :8080 | Listen address |
| `FRANKENPHP_NUM_WORKERS` | 4 | Number of worker processes |
### Memory Management
- Workers automatically restart after `MAX_REQUESTS` to prevent memory leaks
- `gc_collect_cycles()` runs after each request
- Set `MAX_REQUESTS=0` for unlimited requests (development only)
---
## Production Deployment
For production deployments, each server directory in [bear-sunday-servers](https://github.com/bearsunday/bear-sunday-servers) includes:
- `Dockerfile` - Optimized production build
- `docker-compose.prod.yml` - Production configuration
- Health check endpoints
- OPcache optimization
Example production deployment:
```bash
cd swoole # or roadrunner, frankenphp
docker compose -f docker-compose.prod.yml up -d
```
## Benchmarking
See [BEAR.HelloworldBenchmark](https://github.com/bearsunday/BEAR.HelloworldBenchmark) for benchmark comparisons.
## Related
- [Parallel Resource Execution](async.html) - Parallel execution of `#[Embed]` resources with BEAR.Async
## References
- [Swoole](https://www.swoole.com/) - [Documentation](https://wiki.swoole.com/)
- [RoadRunner](https://roadrunner.dev/) - [Documentation](https://roadrunner.dev/docs)
- [FrankenPHP](https://frankenphp.dev/) - [Documentation](https://frankenphp.dev/docs/)
- [BEAR.Swoole](https://github.com/bearsunday/BEAR.Swoole)
- [bear-sunday-servers](https://github.com/bearsunday/bear-sunday-servers)
# Command Line Interface (CLI)
BEAR.Sunday's Resource Oriented Architecture (ROA) represents all application functionality as URI-addressable resources. This approach allows resources to be accessed through various means, not just through the web.
```bash
$ php bin/page.php '/greeting?name=World&lang=fr'
{
"greeting": "Bonjour, World",
"lang": "fr"
}
```
BEAR.Cli is a tool that converts these resources into native CLI commands and makes them distributable via Homebrew, which uses formula scripts to define installation procedures.
```bash
$ greet -n "World" -l fr
Bonjour, World
```
You can reuse existing application resources as standard CLI tools without writing additional code. Through Homebrew distribution, users can utilize these tools like any other command-line tool, without needing to know they're powered by PHP or BEAR.Sunday.
## Installation
Install using Composer:
```bash
composer require bear/cli
```
## Basic Usage
### Adding CLI Attributes to Resources
Add CLI attributes to your resource class to define the command-line interface:
```php
use BEAR\Cli\Attribute\Cli;
use BEAR\Cli\Attribute\Option;
class Greeting extends ResourceObject
{
#[Cli(
name: 'greet',
description: 'Say hello in multiple languages',
output: 'greeting'
)]
public function onGet(
#[Option(shortName: 'n', description: 'Name to greet')]
string $name,
#[Option(shortName: 'l', description: 'Language (en, ja, fr, es)')]
string $lang = 'en'
): static {
$greeting = match ($lang) {
'ja' => 'こんにちは',
'fr' => 'Bonjour',
'es' => '¡Hola',
default => 'Hello',
};
$this->body = [
'greeting' => "{$greeting}, {$name}",
'lang' => $lang
];
return $this;
}
}
```
### Generating CLI Commands and Formula
To convert a resource into a command, run the following command with your application name (vendor name and project name):
```bash
$ vendor/bin/bear-cli-gen 'MyVendor\MyProject'
# Generated files:
# bin/cli/greet # CLI command
# var/homebrew/greet.rb # Homebrew formula
```
Note: Homebrew formula is generated only when a GitHub repository is configured.
## Command Usage
The generated command provides standard CLI features such as:
### Displaying Help
```bash
$ greet --help
Say hello in multiple languages
Usage: greet [options]
Options:
--name, -n Name to greet (required)
--lang, -l Language (en, ja, fr, es) (default: en)
--help, -h Show this help message
--version, -v Show version information
--format Output format (text|json) (default: text)
```
### Showing Version Information
```bash
$ greet --version
greet version 0.1.0
```
### Basic Usage Examples
```bash
# Basic greeting
$ greet -n "World"
Hello, World
# Specify language
$ greet -n "World" -l ja
こんにちは, World
# Short options
$ greet -n "World" -l fr
Bonjour, World
# Long options
$ greet --name "World" --lang es
¡Hola, World
```
### JSON Output
```bash
$ greet -n "World" -l ja --format json
{
"greeting": "こんにちは, World",
"lang": "ja"
}
```
### Output Behavior
CLI command output follows these specifications:
- **Default output**: Displays only the specified field value
- **`--format=json` option**: Displays full JSON response similar to API endpoint
- **Error messages**: Output to standard error (stderr)
- **HTTP status code mapping**: Maps to exit codes (0: success, 1: client error, 2: server error)
## Distribution
Commands created with BEAR.Cli can be distributed via Homebrew.
Formula generation requires the application to be published on GitHub:
### 1. Local Formula Distribution
For testing development versions:
```bash
$ brew install --formula ./var/homebrew/greet.rb
```
### 2. Homebrew Tap Distribution
Method for wide distribution using a public repository:
Note: The file name of the formula and the class name inside it are based on the name of the repository. For example, if the GH repository is `koriym/greet`, then `var/homebrew/greet.rb` will be generated, which contains the `Greet` class. In this case, `greet` will be the name of the tap that is published, but if you want to change it, please change the class name and file name of fomula script.
```bash
$ brew tap your-vendor/greet
$ brew install your-vendor/greet
```
This method is particularly suitable for:
- Open source projects
- Continuous updates provision
#### Testing Development Version
```bash
$ brew install --HEAD ./var/homebrew/greet.rb
```
```bash
$ greet --version
greet version 0.1.0
```
#### Stable Release
1. Create a tag:
```bash
$ git tag -a v0.1.0 -m "Initial stable release"
$ git push origin v0.1.0
```
2. Update formula:
```diff
class Greet < Formula
+ desc "Your CLI tool description"
+ homepage "https://github.com/your-vendor/greet"
+ url "https://github.com/your-vendor/greet/archive/refs/tags/v0.1.0.tar.gz"
+ sha256 "..." # Add hash value obtained from the command below
+ version "0.1.0"
head "https://github.com/your-vendor/greet.git", branch: "main"
depends_on "php@8.1"
depends_on "composer"
end
```
You can add dependencies like databases to the formula as needed. However, it's recommended to handle database setup and other environment configuration in the `bin/setup` script.
3. Get SHA256 hash:
```bash
# Download tarball from GitHub and calculate hash
$ curl -sL https://github.com/your-vendor/greet/archive/refs/tags/v0.1.0.tar.gz | shasum -a 256
```
4. Create Homebrew tap:
Create a repository using [GitHub CLI(gh)](https://cli.github.com/) or [github.com/new](https://github.com/new). The public repository name must start with `homebrew-`, for example `homebrew-greet`:
```bash
$ gh auth login
$ gh repo create your-vendor/homebrew-greet --public --clone
# Or create and clone repository using the web interface
$ cd homebrew-greet
```
5. Place and publish formula:
```bash
$ cp /path/to/project/var/homebrew/greet.rb .
$ git add greet.rb
$ git commit -m "Add formula for greet command"
$ git push
```
6. Installation and distribution:
End users can start using the tool with just these commands. PHP environment and dependency package installation are handled automatically, so users don't need to worry about environment setup:
```bash
$ brew tap your-vendor/greet # homebrew- prefix can be omitted
$ brew install your-vendor/greet
# Ready to use immediately
$ greet --version
greet version 0.1.0
```
## Formula Customization
You can edit the formula using the `brew edit` command as needed:
```bash
$ brew edit your-vendor/greet
```
```ruby
class Greet < Formula
desc "Your CLI tool description"
homepage "https://github.com/your-vendor/greet"
url "https://github.com/your-vendor/greet/archive/refs/tags/v0.1.0.tar.gz"
sha256 "..." # tgz SHA256
version "0.1.0"
depends_on "php@8.4" # Specify PHP version
depends_on "composer"
# Add if required by the application
# depends_on "mysql"
# depends_on "redis"
end
```
## Clean Architecture
BEAR.Cli demonstrates the strengths of both Resource Oriented Architecture (ROA) and Clean Architecture. Following Clean Architecture's principle that "UI is a detail," you can add CLI as a new adapter alongside the web interface for the same resource.
Furthermore, BEAR.Cli supports not only command creation but also distribution and updates through Homebrew. This allows end users to start using tools with a single command, treating them as native UNIX commands without awareness of PHP or BEAR.Sunday.
Additionally, CLI tools can be version-controlled and updated independently from the application repository. This means they can maintain stability and continuous updates as command-line tools without being affected by API evolution. This represents a new form of API delivery, realized through the combination of Resource Oriented Architecture and Clean Architecture.
# Coding Guide
## Project
`Vendor` should be the company name, team name or the owner (`excite`, `koriym` etc.).
`Package` is the name of the application or service (`blog`, `news` etc.).
Projects must be created on a per application basis. Even when you create a Web API and an HTML from different hosts, they are considered one project.
## Style
BEAR.Sunday follows the PSR style.
* [PSR1](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-1-basic-coding-standard.md)
* [PSR2](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md)
* [PSR4](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-4-autoloader.md)
Here is ResourceObject code example.
```php
code = Code::CREATED;
return $this;
}
}
```
A [DocBlock comment]([https://phpdoc.org/docs/latest/getting-started/your-first-set-of-documentation.html]) is optional. A DocBlock contains the method summary in one line.
Then followed by the description, which can be a multiple lines.
We should also put @params after description if possible.
## Resources
See [Resource Best Practices](resource_bp.html) for best practices for resources.
## Globals
We do not recommend referencing global values in resources or application classes. It is only used with Modules.
* Do not refer to the value of [Superglobal](http://php.net/manual/ja/language.variables.superglobals.php)
* Do not use [define](http://php.net/manual/en/function.define.php)
* Do not create `Config` class to hold set values.
* Do not use global object container (service locator) [[1]](http://koriym.github.io/adv10/), [[2]](http://blog.ploeh.dk/2010/02/03/ServiceLocatorisanAnti-Pattern/)
* Use [Date](http://php.net/manual/en/function.date.php) function and [DateTime](http://php.net/manual/en/class.datetime.php) class. It is not recommended to get the time directly. Inject the time from outside using [koriym/now](https://github.com/koriym/Koriym.Now).
Global method calls such as static methods are also not recommended.
The values required by the application code are all injected. The setting files are used for injecting. When you need an external value such as Web API, make a special gateway class for all requests. Then you can mock that special class with DI or AOP.
## Classes and object
* * [Traits](http://php.net/manual/en/language.oop5.traits.php) are not recommended. Traits for injection such as `ResourceInject` that reduce boilerplate code for injection were added in PHP8 [constructor property promotion (declaring properties in the constructor signature)](https://www.php.net/manual/en/language.oop5.decon.php#language.oop5.decon.constructor.promotion). Use constructor injection.
* It is not recommended for the child classes to use the parent class methods. Common functions are not shared by inheritance and trait, they are dedicated classes and they are injected and used. [Composite from inheritance](https://en.wikipedia.org/wiki/Composition_over_inheritance).
* A class with only one method should reflect the function to the class name and should set the name of the method to `__invoke ()` so that function access can be made.
## Script command
* It is recommended to end the setup by using the `composer setup` command. This script includes the necessary database initialization and library checking. If manual operation such as `.env` setting is required, it is recommended that the procedure be displayed on the screen.
* It is recommended that all application caches and logs are cleared with `composer cleanup` command.
* It is recommended that all executable test (phpinit/phpcs/phpmd ..) are invoked with `composer test` command.
* It is recommended an application is deployed with `composer deploy` command.
## Code check
It is recommended to check the codes for each commit with the following commands. These commands can be installed with [bear/qatools](https://github.com/bearsunday/BEAR.QATools).
```
phpcs src tests
phpmd src text ./phpmd.xml
php-cs-fixer fix --config-file=./.php_cs
phpcbf src
```
## Resources
Please also refer to [Resouce best practice](/manuals/1.0/en/resource.html#best-practice).
### Code
Returns the appropriate status code. Testing is easier, and the correct information can be conveyed to bots and crawlers.
* `100` Continue Continuation of multiple requests
* `200` OK
* `201` Created Resource Creation
* `202` Accepted queue / batch acceptance
* `204` If there is no content body
* `304` Not Modified Not Updated
* `400` Bad request
* `401` Unauthorized Authentication required
* `403` Forbidden ban
* `404` Not Found
* `405` Method Not Allowed
* `503` Service Unavailable Temporary error on server side
In `OnPut` method, you deal with the resource state with idempotence. For example, resource creation with UUID or update resource state.
`OnPatch` is implemented when changing the state of a part of a resource.
### HTML Form Method
BEAR.Sunday can overwrite methods using the `X-HTTP-Method-Override` header or` _method` query at the `POST` request in the HTML web form, but it is not necessarily recommended . For the Page resource, it is OK to implement policies other than `onGet` and` onPost`. [[1]](http://programmers.stacxchange.com/questions/114156/why-are-there-are-no-put-and-delete-methods-on-html-forms), [[2]](Http://roy.gbiv.com/untangled/2009/it-is-okay-to-use-post)
### Hyperlink
* It is recommended that resources with links be indicated by `#[Link]`.
* It is recommended that resources be embedded as a graph of semantic coherence with `#[Embed]`.
## DI
* Do not inject the value itself of the execution context (prod, dev etc). Instead, we inject instances according to the context. The application does not know in which context it is running.
* Setter injection is not recommended for library code.
* It is recommended that you override the `toConstructor` bindings instead and avoid the `Provider` bindings as much as possible.
* Avoid binding by `Module` according to conditions. [AvoidConditionalLogicInModules](https://github.com/google/guice/wiki/AvoidConditionalLogicInModules)
* It is not recommended to reference environmental variables since there is no module. Pass it in the constructor.
## AOP
* Do not make interceptor mandatory. We will make the program work even without an interceptor. (For example, if you remove `#[Transactional]` interceptor, the function of transaction will be lost, but "core concerns" will work without issue.)
* Prevent the interceptor from injecting dependencies in methods. Values that can only be determined at implementation time are injected into arguments via `#[Assisted]` injection.
* If there are multiple interceptors, do not depend on the execution order.
* If it is an interceptor unconditionally applied to all methods, consider the description in `bootstrap.php`.
## Environment
To make applications testable, it should also work on the console, and not only on the Web.
It is recommended not to include the `.env` file in the project repository.
## Testing
* Focus on resource testing using resource clients, adding resource representation testing (e.g. HTML) if needed.
* Hypermedia tests can leave use cases as tests.
* `prod` is the context for production. Use of the `prod` context in tests should be minimal, preferably none.
## HTML templates
* Avoid large loop statements. Consider replacing if statements in loops with [Generator](https://www.php.net/manual/en/language.generators.overview.php).
---
# PHPDoc Utility Types
Utility types are type operators that derive keys, values, property maps, or indexed value types from existing types. For the broader PHPDoc type reference, see [PHPDoc Types](types.html).
Some types, such as `properties-of` and `class-string-map`, are Psalm-specific, so check the analyzer you use before adopting them.
## key-of