diff --git a/manuals/1.0/en/15.tech.md b/manuals/1.0/en/15.tech.md index ad508a7f..fc8fff5b 100644 --- a/manuals/1.0/en/15.tech.md +++ b/manuals/1.0/en/15.tech.md @@ -4,21 +4,24 @@ title: Technology category: Manual permalink: /manuals/1.0/en/tech.html --- + # Technology This chapter explains the features and technical characteristics of BEAR.Sunday. -## Resource Oriented Architecture (ROA) +## Architecture and Design Principles + +### Resource Oriented Architecture (ROA) > "Resources interconnected, like the web of life that binds all creatures." -BEAR.Sunday's ROA is an architecture that realizes RESTful APIs within a web application. This is the core of BEAR.Sunday's design principles and serves as both a hypermedia framework and "Object as a Service". As with the Web, all data and functions are treated as resources and are manipulated through standardized interfaces such as GET, POST, PUT, and DELETE. +BEAR.Sunday's ROA is an architecture for implementing RESTful APIs within web applications. It is the core of BEAR.Sunday's design principles and serves as both a hypermedia framework and an "object as a service". Just like the Web, all data and functions are treated as resources and are manipulated through standardized interfaces such as GET, POST, PUT, and DELETE. -### URI +#### URI -URIs (Uniform Resource Identifiers) are a key element to the success of the Web and are at the core of BEAR.Sunday's ROA. By assigning URIs to all resources handled by the application, resources can be easily identified and accessed. URIs not only function as identifiers for resources but are also used to express relationships between resources. This makes it easy to manipulate, reuse, and combine resources. +URI (Uniform Resource Identifier) is a key element to the success of the Web and is also at the heart of BEAR.Sunday's ROA. By assigning URIs to all resources handled by the application, resources become identifiable and easily accessible. URIs serve not only as identifiers for resources but are also used to express relationships between resources. This facilitates the manipulation, reuse, and combination of resources. -### Uniform Interface +#### Uniform Interface Access to resources is done using HTTP methods (GET, POST, PUT, DELETE). These methods define the operations that can be performed on resources and provide a common interface regardless of the type of resource. @@ -27,210 +30,246 @@ Access to resources is done using HTTP methods (GET, POST, PUT, DELETE). These m - PUT: Performs an idempotent operation on a resource (e.g., creation or update) - DELETE: Deletes a resource -## Hypermedia +#### Hypermedia -In BEAR.Sunday's ROA, each resource provides affordances (operations and functions available to the client) through hyperlinks. These links represent the operations available to the client and instruct how to navigate within the application. This reduces coupling between client and server and enhances the flexibility and expandability of the application. +In BEAR.Sunday's ROA, each resource provides affordances (available operations or functions for the client) through hyperlinks. These links represent the operations available to the client and provide instructions on how to navigate within the application. This reduces the coupling between the client and server and increases the flexibility and extensibility of the application. -Hyperlinks not only indicate relationships between resources but also function as a mechanism for embedding resources. This is similar to how images are embedded using the IMG tag in HTML. In BEAR.Sunday, resources are accessible as independent entities, and the content tree structure is formed by declaratively building relationships between resources through internal links. +Hyperlinks not only indicate relationships between resources but also function as a mechanism to embed resources. This is similar to how images are embedded in HTML using the IMG tag. In BEAR.Sunday, resources are accessible as independent entities, and relationships between resources are declaratively constructed through internal links, forming a tree structure of content. -BEAR.Sunday's hypermedia approach is a design that follows Web principles and enhances the flexibility and expandability of applications. +BEAR.Sunday's hypermedia approach aligns with the principles of the Web and enhances the flexibility and extensibility of applications. -### Separation of Value and Representation +#### Separation of Value and Representation -In BEAR.Sunday's ROA, the value and representation of resources are clearly separated. The value of a resource is managed by the application's domain logic, while the representation is for expressing that value in various formats (e.g., JSON, XML, HTML). This separation results in loose coupling between domain logic and presentation logic, improving the maintainability and expandability of the application. +In BEAR.Sunday's ROA, the value and representation of resources are clearly separated. The value of a resource is managed by the application's domain logic, while the representation is used to present that value in various formats (JSON, XML, HTML, etc.). This separation results in loose coupling between domain logic and presentation logic, improving the maintainability and extensibility of the application. -### Page Resources and App Resources +#### Page Resources and App Resources -In BEAR.Sunday's ROA, resources are classified into two types: page resources and app resources. +In BEAR.Sunday's ROA, resources are classified into two categories: page resources and app resources. -- Page Resources: Mainly resources with HTML representation, intended to be accessed from a web browser. They constitute the user interface resources. -- App Resources: Resources that make up the application's backend, mainly with JSON or XML representation. They are intended to be accessed by other applications or services. +- Page Resources: Primarily resources with HTML representation, intended to be accessed from web browsers. These resources constitute the user interface. +- App Resources: Resources that make up the application's backend, primarily using JSON or XML representations. They are intended to be accessed by other applications or services. -By separating page resources and app resources, the user interface and application logic can be developed and deployed independently. Also, by reusing app resources, a consistent backend can be provided to multiple user interfaces (web browsers, mobile apps, other services, etc.). +Separating page resources and app resources allows independent development and deployment of the user interface and application logic. Additionally, by reusing app resources, a consistent backend can be provided to multiple user interfaces (web browsers, mobile apps, other services, etc.). -Using BEAR.Sunday's ROA, scalable and loosely coupled applications that follow Web design principles can be built. The separation of value and representation allows domain logic and presentation logic to be developed and tested independently, improving application quality and development efficiency. Also, separating page resources and app resources allows user interfaces and application logic to be developed and deployed independently, enhancing the flexibility and expandability of the application. Hyperlinks also make the relationships between resources explicit, keeping coupling between client and server low and enhancing the self-descriptive nature of resources and the discoverability of APIs. +Using BEAR.Sunday's ROA, scalable and loosely coupled applications can be built in alignment with the design principles of the Web. The separation of value and representation allows independent development and testing of domain logic and presentation logic, improving application quality and development efficiency. Furthermore, separating page resources and app resources enables independent development and deployment of the user interface and application logic, enhancing the flexibility and extensibility of the application. Hyperlinks also make the relationships between resources explicit, keeping coupling between the client and server low while enhancing the self-descriptiveness and discoverability of APIs. -### Differences from MVC +#### Differences from MVC -BEAR.Sunday's ROA takes a different approach from the conventional MVC architecture. MVC composes an application with three components: model, view, and controller, but in reality, the controller freely manipulates the model and view at runtime, and the controller literally controls everything. +BEAR.Sunday's ROA takes a different approach compared to the traditional MVC architecture. MVC composes an application with three components: Model, View, and Controller. In practice, however, the Controller freely manipulates the Model and View at runtime, with the Controller literally controlling everything. -In contrast, in BEAR.Sunday, a view is injected into the resource object. The resource is unaware of the view, and at the same time, the view is also unaware of the resource. The resource object does not perform any operations on the injected view and does not even know what kind of view was injected. While resource methods are only concerned with the resource state, the injected resource view only renders the resource state into a string representation when the resource object is string evaluated. In this way, resources and views are loosely coupled, and their responsibilities are clearly separated. +In contrast, in BEAR.Sunday, the View is injected into the resource object. The resource is oblivious to the View, and the View is also oblivious to the resource. The resource object does not perform operations on the injected View and does not even know what kind of View has been injected. While the resource's methods are only concerned with the resource state, the injected resource View renders the resource's state into a string representation only when the resource object is string-evaluated. In this way, the resource and View are loosely coupled, and their responsibilities are clearly separated. -Also, in contrast to the unconstrained relationship between controller and model, resources have a constraint on containing other resources using URIs, and this can be done declaratively. That resource again depends on different resources, forming a tree structure like dependencies in DI. Other differences include: +Furthermore, unlike the relationship between the Controller and Model where there are no constraints, resources have constraints on including other resources using URIs, and this can be done declaratively. That resource depends on another resource, forming a tree structure like DI dependencies. Other differences include: -- BEAR.Sunday resources provide possible operations (affordances) by declaring relations, making them self-descriptive. +- BEAR.Sunday's resources provide possible operations (affordances) by declaring relationships. They are self-descriptive. - HAL (Hypertext Application Language) is adopted to standardize links between resources. -- Unlike MVC models, resources can be called directly from various clients including the console. -- There is no need to build HTML sites and API sites separately; HTML sites and API sites can be built simultaneously using the same resources. +- Unlike MVC models, resources can be directly called from a variety of clients, including the console. +- There is no need to build HTML sites and API sites separately; both HTML sites and API sites can be built simultaneously using the same resources. -## Dependency Injection (DI) +### Dependency Injection (DI) -> "Objects are injected from the interface, just as sun ray is injected when a window is opened." +> "Objects are injected from the interface, just as sun rays are injected when a window is opened." Dependency Injection (DI) is an important technique for enhancing the design and structure of applications in object-oriented programming. The central purpose of DI is to divide an application's functionality into multiple components with independent domains or roles and manage the dependencies between them. -DI helps horizontally divide a single function into multiple functions. The divided functions can be independently developed and tested as "dependencies". Based on the single responsibility principle, injecting those dependencies with clear responsibilities and roles from the outside improves object reusability and testability. Dependencies are also divided vertically into other dependencies, forming a dependency tree. This dependency tree is called an object graph, and the main role of DI is to become the builder of this object graph. +DI helps horizontally divide a single function into multiple functions. The divided functions can be independently developed and tested as "dependencies" with clear responsibilities and roles based on the single responsibility principle. Injecting those dependencies from the outside, with clear responsibilities and roles, improves the reusability and testability of objects. Dependencies are also vertically divided into other dependencies, forming a dependency tree. This dependency tree is called an object graph, and the main role of DI is to become the builder of this object graph. -Using DI improves the structure of the application and loosens the coupling between components. This helps adhere to many of the best practices in object-oriented programming, resulting in code that is easier to manage and testable. However, these are merely secondary benefits, and the main purpose of DI is to design and build loosely coupled applications following the principle of "divide and conquer". +Using DI improves the structure of the application and loosens the coupling between components. This helps adhere to many of the best practices in object-oriented programming, resulting in code that is manageable and testable. However, these are merely secondary benefits, and the primary purpose of DI is to design and build loosely coupled applications following the principle of "divide and conquer". -BEAR.Sunday's DI uses an independent package called [Ray.Di](https://github.com/ray-di/Ray.Di), which incorporates the design philosophy of Google's DI framework Guice and covers almost all of its features. +BEAR.Sunday's DI uses an independent package called [Ray.Di](https://github.com/ray-di/Ray.Di), which adopts the design philosophy of Google's DI framework, Guice, and covers almost all of its features. -### Binding by Context +#### Context-based Binding -For example, consider an application with two contexts, HTML and PROD, on top of the base application. In the HTML context, the binding for resource representation changes from JSON view to HTML view. In PROD, the cache interface bound to Array cache is bound to Redis cache. By overlaying bindings from multiple contexts, the application code can behave differently without any changes. +For example, consider an application with a base application and two contexts: HTML and PROD. In the HTML context, the JSON view bound to the resource representation changes to an HTML view binding. In PROD, the Array cache interface bound to the cache interface is bound to the Redis cache. By layering the bindings of multiple contexts, the application can exhibit different behaviors without changing the application code. -Instead of using IF statements to check if it's in DEBUG mode and change behavior at runtime, dependencies with different implementations are bound according to the context. +Instead of using IF statements to check if it is in DEBUG mode and change the behavior at runtime, different implementations are bound according to the context. -Other features include: +Other characteristics include: -* Attribute-based configuration enhances code self-descriptiveness. -* Using qualifiers to bind different implementations to the same interface also enhances code self-descriptiveness. +* The self-descriptiveness of the code is enhanced through attribute-based configuration. +* The self-descriptiveness of the code is further enhanced by using qualifiers to bind different implementations to the same interface. * Ray.Di resolves dependencies at compile time, improving runtime performance. This is different from other DI containers that resolve dependencies at runtime. -* Object dependencies can be visualized in a graph. ex) [application skeleton](/images/app.svg) -* In addition to link binding, instance binding, and others, various bindings are supported such as attribute binding, untarget binding, multi-binding, construct binding, context binding, and Null binding. -* Dependencies with high instantiation costs can be lazily bound to obtain instances at runtime. +* The dependency graph of objects can be visualized. For example, [Application Skeleton](/images/app.svg). +* In addition to link binding, instance binding, and other bindings, there are also attribute binding, untarget binding, multi-binding, construct binding, context binding, null binding, and various other bindings supported. +* For dependencies with a large cost for instantiation, lazy binding can be used to obtain instances at runtime. * Bindings can be grouped into modules for reuse. Ray.Di logo -## Aspect Oriented Programming (AOP) +### Aspect-Oriented Programming (AOP) > "Aspects wrap your objects, like a gift wrap enhances a present." -Aspect-oriented programming (AOP) is a pattern that realizes flexible applications by separating core concerns such as business logic from cross-cutting concerns such as logging and caching. Cross-cutting concerns refer to functionalities or processes that span across multiple modules or layers. +Aspect-Oriented Programming (AOP) is a pattern for achieving flexible applications by separating core concerns, such as business logic, from cross-cutting concerns, such as logging and caching. Cross-cutting concerns refer to functionality or processing that spans multiple modules or layers. -BEAR.Sunday's AOP uses an independent package called Ray.Aop and declaratively binds cross-cutting processes by attaching PHP attributes to classes or methods. Ray.Aop conforms to Java's [AOP Alliance](https://aopalliance.sourceforge.net/) and has the following features: +BEAR.Sunday's AOP uses an independent package called Ray.Aop, which declaratively binds cross-cutting processing by attaching PHP attributes to classes or methods. Ray.Aop conforms to Java's [AOP Alliance](https://aopalliance.sourceforge.net/) and has the following characteristics: * The declarative description method using attributes improves code readability. -* Cross-cutting processes can be bound based on search conditions, allowing for flexible configurations based on context. +* Cross-cutting processing can be bound based on search conditions, allowing flexible configuration based on context. -AOP is one of the most misunderstood technologies. Its purpose is not to ignore constraints and disrupt order for the sake of powerful capabilities, but rather to complement areas where object-orientation is not adept, such as exploratory feature allocation and separation of cross-cutting processes. In other words, it is one of the paradigms that makes it possible to create application-wide constraints, that is, to design as application framework constraints. +AOP is one of the most misunderstood technologies. Its raison d'être is not to ignore constraints and disrupt order for the sake of powerful capabilities. Instead, it is one of the paradigms that complements areas where object-oriented programming is not well-suited, such as exploratory feature assignment and separation of cross-cutting concerns, and makes it possible to design application-wide constraints, i.e., constraints as an application framework. -## Event-Driven Content Strategy Based on ROA with Integration of Modern CDN +## Performance and Scalability + +### ROA-based Event-driven Content Strategy Integrated with Modern CDNs > "No volatility, just what users truly desire." -BEAR.Sunday realizes an advanced event-driven caching strategy by integrating with instant purge-capable CDNs such as Fastly, with ROA at its core. Instead of invalidating caches based on conventional TTL (Time to Live), this strategy immediately invalidates the CDN cache, server-side cache, and ETag (Entity Tag) based on resource state change events. +BEAR.Sunday achieves an advanced event-driven caching strategy by integrating with instant-purgeable CDNs such as Fastly, with Resource-Oriented Architecture (ROA) at its core. Instead of invalidating caches based on traditional TTL (Time to Live), this strategy instantly invalidates CDN and server-side caches, as well as ETags (Entity Tags), in response to resource state change events. + +This approach, which eliminates volatility, 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 of the Web for dynamic content as for static content, which the Web has had since the 1990s. In other words, it re-implements the principle of distributed caching, which scales and reduces network costs, using modern technologies. + +#### Cache Invalidation through Semantic Methods and Dependencies + +In BEAR.Sunday's ROA, each resource operation is assigned a semantic (meaningful role). For example, the GET method retrieves a resource, while the PUT method updates a resource. These methods collaborate in an event-driven manner to efficiently invalidate related caches. For instance, when a specific resource is updated, the caches of resources that depend on that resource are invalidated. This ensures data consistency and freshness, providing users with the latest information. + +#### Identity Verification and Quick Response using ETag -This approach that eliminates volatility 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 Web's original distributed caching that scales and reduces network costs even for dynamic content, just like static content. In other words, it re-implements the principle of distributed caching that the Web has had since the 1990s using modern technologies. +By setting ETag before the system boots, the identity of the content can be quickly verified, and if there are no changes, a 304 Not Modified response is returned. This is an effective technique for reducing network load and improving user experience. -### Cache Invalidation by Semantic Methods -In BEAR.Sunday's ROA, each resource operation is given a semantic role. For example, the GET method retrieves a resource, while the PUT method updates a resource. These methods work together in an event-driven manner and efficiently invalidate related caches. For instance, when a specific resource is updated, that change automatically propagates to other resources that depend on it, and related caches are invalidated. This maintains data consistency and freshness, providing users with the latest information. +#### Partial Updates with Donut Caching and ESI -### Visualizing Dependencies through Embedded Links -In ROA design, resources can contain links to other resources, transparently showing resource dependencies to the client. By utilizing this link information, it can be instantly determined which resources are affected when cache invalidation is necessary, enabling efficient cache management. +BEAR.Sunday adopts a donut caching strategy and uses Edge Side Includes (ESI) to enable partial content updates at the CDN edge. This technology allows dynamic updates of only the necessary parts without re-caching the entire page, significantly improving performance and caching efficiency. -### Cache Key Generation by Argument Declaration -In BEAR.Sunday, resource method arguments are clearly declared. This allows generating custom cache keys based on the resource state or request parameters. Cache key generation is an important mechanism for accurately identifying specific caches when the resource state changes and invalidating them. This allows avoiding unnecessary cache deletion while quickly updating only the necessary parts. +Thus, the ROA-based caching strategy integrated with Fastly and BEAR.Sunday not only realizes advanced distributed caching but also enhances application performance and fault tolerance. This allows users to experience consistent responsiveness and data integrity under any circumstances. -### Quick Response and Identity Confirmation with ETag -By setting the ETag before the system boots, the identity of the content can be quickly verified, and a 304 Not Modified response is returned if there are no changes. This is an effective technique for reducing network load and improving user experience. +### Boot Acceleration -### Partial Updates with Donut Hole Caching and ESI -BEAR.Sunday adopts the donut hole caching strategy and uses Edge Side Includes (ESI) to enable partial content updates at the CDN edge. This technology allows dynamically updating only the necessary parts without re-caching the entire page, significantly improving performance and caching efficiency. +In the world of DI, users ideally do not directly deal with the injector (DI container) as much as possible. Instead, at the application's entry point, a single root object is created to start the application. In BEAR.Sunday's DI, there is essentially no DI container manipulation even at configuration time. The root object is huge but a single variable, so it is reused across requests to achieve an extremely optimized bootstrap. -In this way, BEAR.Sunday's ROA-based caching strategy integrated with Fastly not only realizes advanced distributed caching but also enhances application performance and fault tolerance. This allows users to experience consistent responsiveness and data integrity under any circumstances. +## Developer Experience -## Ease of Testing +### Ease of Testing -BEAR.Sunday allows for easy and effective testing due to the following design characteristics: +BEAR.Sunday facilitates easy and effective testing due to the following design characteristics: -* Each resource is independent, and testing is easy due to the nature of stateless requests in REST. -* Since the state and representation of resources are separated, it is possible to test the state of resources even when the representation is HTML. -* API testing can be done by following hypermedia links, using the same code in PHP and HTTP. +* Each resource is independent, and the stateless request nature of REST makes testing straightforward. +* With the separation of resource state and representation, it is possible to test the resource state even when using HTML representation. +* API testing can be performed by following hypermedia links, using the same code in PHP and HTTP. * Context-based binding allows binding different implementations during testing. Bindings can be changed for the entire "test context" or temporarily for a specific test. -* The ResourceObject includes `header` meta-information, allowing for testing based on meta-information. For example, if the content is cached, the presence of caching can be tested by checking the `Age` header. Compare this with MVC models. +* ResourceObject includes `header` meta-information, enabling testing based on meta-information. For example, if the content is cached, the presence or absence of caching can be tested by checking the `Age` header. Compare this to MVC models. * Resources embedded with `#[Embed]` embed resource requests, not values. The intention of what kind of resource to embed can be tested. -## Resource Validation +### Visualization and Debugging -JsonSchema is used to validate resource representations and maintain resource consistency. Using standard schemas for validation enables the use of external tools. +* During development, the scope and tools of resources are displayed graphically on HTML. +* Resource states can be checked on the web interface, and PHP code and HTML templates can be edited online and reflected in real-time. -## Stream Output -* Streaming output of resource representations allows outputting large-scale content that cannot be handled in memory. -* Streams can coexist with normal value assignments. +### API Documentation Generation + +API documentation is automatically generated from the code. This maintains consistency between the code and documentation, enhancing maintainability. -## Visualization and Debugging +## Extensibility and Integration -* During development, the scope and tools of resources are graphically displayed on HTML. -* The state of resources can be checked on the web page, and PHP code and HTML templates can be edited online and reflected in real-time. +### Resource Validation -## Startup Acceleration +Resource representations are validated using JsonSchema to maintain resource consistency. Using standard schemas for validation allows the use of external tools. -* Pre-compilation generates PHP code for dependency generation, achieving minimal bootstrapping. -* In an ideal DI world, instances are generated only once at startup. This is called the root object, and by caching this root object, initialization can be reused to accelerate application startup. +### Integration of PHP Interfaces and SQL Execution -## Integration of PHP Interfaces and SQL Execution -In BEAR.Sunday, SQL statements for interacting with the database can be easily managed using PHP interfaces. It is possible to bind SQL execution objects directly to interfaces without implementing classes. This improves code reusability and enhances modularity. +In BEAR.Sunday, PHP interfaces can be used to easily manage the execution of SQL statements for interacting with the database. Instead of implementing classes, SQL execution objects can be directly bound to PHP interfaces. This improves code reusability and enhances modularity. -### Evaluation of Query Arguments -BEAR.Sunday interfaces can accept not only scalar values but also objects. In particular, how objects are evaluated by the interface is important. For example, when a DateTimeInterface object is passed to an interface, it is automatically evaluated appropriately as a date within the SQL statement. This allows efficient handling of date and time data. +### Query Argument Evaluation -### Dependency Injection of Query Arguments -In BEAR.Sunday, it is also possible to inject dependencies into interfaces. This allows dynamically supplying necessary objects and values to interfaces, enabling more flexible application design. Using dependency injection makes code testing easier and maintains low coupling while maintaining high cohesion. +PHP interfaces bound to SQL execution can accept not only scalar values but also objects as arguments. For example, if there is a DateTimeInterface argument, the bound current time is automatically evaluated as a date string to be properly handled as a date within the SQL statement. The self-resolving PHP interface reduces the burden of resolving arguments passed to SQL and improves code readability. -### SQL Generation and Optimization Using AI and Tools -In BEAR.Sunday, it is also possible to inject dependencies into interfaces. This allows dynamically supplying necessary objects and values to interfaces, enabling more flexible application design. Using dependency injection makes code testing easier and maintains low coupling while maintaining high cohesion. +#### SQL Generation and Optimization using AI and Tools + +In BEAR.Sunday, dependencies can also be injected into interfaces. This allows necessary objects and values to be dynamically supplied to interfaces, enabling more flexible application design. Using dependency injection makes code testing easier, maintaining low coupling while achieving high cohesion. ### Comprehensive Debugging and Maintenance Convenience -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 issues. Also, since queries can be modified and functionalities can be expanded directly, application maintenance and evolution proceed smoothly. + +The direct management of SQL facilitates debugging when errors occur. The behavior of SQL queries can be directly observed, allowing quick identification and correction of problems. Additionally, query modifications and feature extensions can be performed directly, making application maintenance and evolution smooth. * PHP interfaces and SQL can be prepared, and SQL execution objects can be bound to PHP interfaces without implementing classes. -* PHP interfaces can specify not only scalar values but also objects to be evaluated as strings. For example, specifying DateTimeInterface will evaluate it as a date in SQL. +* PHP interfaces can accept not only scalar values but also objects to be evaluated as strings. For example, specifying DateTimeInterface will evaluate it as a date in SQL. * Dependencies can be injected as arguments into PHP interfaces. -## API Documentation Generation +### Integration with Other Systems -API documentation is automatically generated from code. This maintains consistency between code and documentation and improves maintainability. +* Integrate with console applications to make all resources accessible from both the web and command line without changing the source code. +* Different applications can be executed concurrently within the same PHP runtime, making all resources accessible from an HTTP client. +* Local and remote BEAR.Sunday applications can be treated similarly, and BEAR.Thrift enables integration with applications in other languages. + +### Stream Output + +* By streaming the representation of resources, large-scale content that cannot be handled in memory can be output. +* Streams can coexist with normal value assignments. -## Integration with Other Systems +### Gradual Migration from Other Systems -* Integration with console applications allows access from both the web and command line without changing the source code. -* Different applications can be executed concurrently within the same PHP runtime, allowing access to all resources from an HTTP client. -* Local and remote BEAR.Sunday applications can be handled similarly, and BEAR.Thrift allows integration with applications in other languages. +BEAR.Sunday provides a gradual migration path, enabling 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 functionality into their existing codebase. -## Standards Compliance +### Flexibility in Technology Migration -* JSON format and www-form format are supported by default, and resource requests are interpreted according to the content type. +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 built resources will not be wasted. In the PHP environment, BEAR.Sunday applications can be integrated as Composer packages for continuous use, and with BEAR.Thrift, BEAR.Sunday resources can be efficiently accessed from other languages. Even without using Thrift, access via HTTP is possible. SQL code reuse is also straightforward. + +If the dependent libraries strongly rely on a specific PHP version or library, making it difficult to upgrade to the latest PHP version, different PHP versions can coexist using BEAR.Thrift. + +## Design Philosophy and Quality + +### Adherence to Standards + +* JSON format and www-form format are supported by default, and resource requests are interpreted based on the content type. * Semantic versioning is adopted to maintain backward compatibility. -* By default, errors are returned in the `vnd.error+json` media type format, returning error messages including error details. +* Errors are returned in the `vnd.error+json` media type format by default, including detailed error messages. * ETag is used to invalidate caches when the resource state changes. -* When caching, HTTP headers such as `Cache-Control`, `Ages`, `Last-Modified`, and `ETag` are added in addition to the `Cache-Control` header. +* When caching, HTTP headers such as `Cache-Control`, `Age`, `Last-Modified`, and `ETag` are included in the HTTP headers. -## Object-Oriented Principles +### Object-Oriented Principles -BEAR.Sunday emphasizes object-oriented principles to make applications maintainable in the long term. +BEAR.Sunday emphasizes object-oriented principles to keep applications maintainable in the long run. ### Composition over Inheritance -Composition is recommended over inheritance classes. In general, directly calling methods of the parent class from the child class may increase coupling between classes. The only abstract class that requires inheritance at runtime from a design perspective is `BEAR\Resource\ResourceObject`, the resource class, but this also exists solely for other classes to use ResourceObject methods. In BEAR.Sunday, there is no class where the user calls methods of an inherited framework parent class at runtime. +Composition is recommended over inheritance classes. In general, directly calling parent class methods from child classes can potentially increase coupling between classes. At runtime, the only abstract class that requires inheritance by design is the `BEAR\Resource\ResourceObject` class for resource classes, but its methods exist solely for the use of other classes. In BEAR.Sunday, there is no case where a user calls a method of an inherited framework parent class at runtime in any class. ### Everything is Injected -Framework classes do not refer to "configuration files" or "debug constants" at runtime to determine behavior. Dependencies corresponding to behavior are injected. This means that to change the behavior of the application, you don't need to change the code, but only change the binding of the implementation to the interface for dependencies. APP_DEBUG or APP_MODE constants do not exist. There is no way to know which mode the software is currently running in after it starts, and there is no need to know. +Framework classes do not refer to "configuration files" or "debug constants" at runtime to determine their behavior. Dependencies with behavior corresponding to the context are injected. This means that to change the application's behavior, there is no need to change the code; only the binding of the dependency implementation to the interface needs to be changed. Constants like APP_DEBUG or APP_MODE do not exist. There is no way to know what mode the software is currently running in after it has started, nor is there a need to know. -### Root Object +### Non-Destructive Backward Compatibility -In the original DI world, users avoid directly handling the injector (DI container) as much as possible. Instead, a single root object is created at the application's entry point to start the application. In BEAR.Sunday's DI, there is essentially no DI container manipulation even at configuration time. The root object is huge but is a single variable, so it is reused beyond requests to realize a highly optimized bootstrap. +BEAR.Sunday is designed to prioritize the maintenance of backward compatibility in software evolution. In modern software development, frequent breaking of backward compatibility and the associated burden of modifications and testing have become a challenge, but BEAR.Sunday aims to avoid this problem and has been successful. -## Non-Destructive Backward Compatibility +This does not mean stopping the evolution of software. The Web has been changing for decades, but its core parts have remained unchanged, and backward compatibility has been maintained. BEAR.Sunday is designed to apply this spirit of the Web to application frameworks as well. -BEAR.Sunday is designed with an emphasis on maintaining backward compatibility in the evolution of software. In modern software development, frequent breakage of backward compatibility and the resulting burden of modifications and testing have become a challenge, but BEAR.Sunday aims to avoid this problem and has been successful. +BEAR.Sunday adopts semantic versioning to prevent new feature additions or changes to existing features from affecting existing code. Deprecated code is given the "deprecated" attribute but is never removed, and it does not affect the behavior of existing code. Instead, new features are added, and evolution continues. -This doesn't mean stopping the evolution of software. The Web has been changing for decades, but its core has remained unchanged and backward compatibility has been maintained. BEAR.Sunday is designed to apply this spirit of the Web to application frameworks as well. +In fact, since its release during PHP 5.4, BEAR.Sunday has had many features added, but existing applications continue to function without modification. Furthermore, with the utilization of static analysis tools that have come with the evolution of the PHP ecosystem, the code has become cleaner and faster. -BEAR.Sunday adopts semantic versioning to prevent new feature additions and changes to existing features from affecting existing code. Deprecated code is given the "deprecated" attribute but is never deleted and does not affect the behavior of existing code. Instead, new features are added and evolution continues. +This design approach, which makes backward compatibility an absolute imperative, and the semantic versioning approach make this long-term compatibility maintenance possible. This allows developers to confidently adopt BEAR.Sunday and benefit from the evolving ecosystem. -In fact, since its release in PHP 5.4, many features have been added to BEAR.Sunday, but existing applications continue to function without modification. Furthermore, with the utilization of static analysis tools and other advancements in the PHP ecosystem, the code has become cleaner and faster. +### Code Quality -The design that makes backward compatibility an absolute proposition and the approach of semantic versioning enable this long-term compatibility. This allows developers to confidently adopt BEAR.Sunday and benefit from the evolving ecosystem. +To provide high-quality applications, the BEAR.Sunday framework itself maintains a high standard of code quality. -## Code Quality - -To deliver high-quality applications, the BEAR.Sunday framework itself maintains a high standard of code quality. - -* The framework code applies the maximum level of both psalm and phpstan static analysis tools. +* The framework code is applied with the strictest levels of both the psalm and phpstan static analysis tools. * 100% test coverage is maintained. * Type coverage is also nearly 100%. The use of mixed types is minimized. -* It is fundamentally an immutable system and is so clean that re-initialization is unnecessary even in tests. It unleashes the power of PHP's asynchronous communication engines like Swoole. +* It is fundamentally an immutable system and is clean enough that reinitialization is not required for each test. It unleashes the power of PHP's asynchronous communication engines like Swoole. + +## The Value Provided by BEAR.Sunday + +### Value for Developers + +- Increased Productivity: With robust design patterns and principled constraints, developers can focus on core business logic. +- Team Collaboration: By providing consistent guidelines and structure to development teams, the code of different engineers is kept unified and loosely coupled, improving code readability and maintainability. +- Improved Maintainability: BEAR.Sunday's non-breaking backward compatibility and unchanging constraints reduce maintenance costs and enhance the long-term continuity of software. +- Flexibility and Extensibility: BEAR.Sunday's policy of not including libraries brings flexibility and freedom for developers in choosing components, allowing for adaptability to future changes. +- Ease of Testing: BEAR.Sunday's DI (Dependency Injection) and ROA (Resource-Oriented Architecture) enhance the ease of testing. + +### Value for Users + +- High Performance: BEAR.Sunday's optimized fast boot and CDN (Content Delivery Network)-centric caching strategy deliver theoretically maximum performance, allowing users to enjoy fast and responsive experiences. +- Reliability and Availability: BEAR.Sunday's CDN-centric caching strategy minimizes single points of failure (SPOF) and achieves reliability and availability to the extent of continuing service delivery even if the PHP or DB server goes down. Users can enjoy stable services that do not go down. +- Ease of Use: BEAR.Sunday's excellent connectivity makes it easy to collaborate with other languages and systems. + +### Value for Businesses + +- 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 enhances technical continuity, minimizing the time and cost of change management. +- High Scalability: With techniques like DI (Dependency Injection) and AOP (Aspect-Oriented Programming) that allow changing behavior while minimizing code changes, BEAR.Sunday enables applications to be easily expanded in line with business growth and changes. +- Excellent User Experience (UX): By delivering high performance and high availability, BEAR.Sunday enhances user satisfaction. Excellent UX contributes to improved customer loyalty, expansion of the customer base, and business success. +Great constraints do not change. The constraints brought by BEAR.Sunday provide concrete value to developers, users, and businesses alike.