From 68c17f707a17868730f5b72305d2e229274166be Mon Sep 17 00:00:00 2001 From: Akihito Koriyama Date: Fri, 19 Apr 2024 01:59:38 +0900 Subject: [PATCH] Refine technical manual with detailed testing guidance This update introduces extensive details and clearer instructions for conducting tests in various contexts, utilizing header metadata and resource embedding. These improvements aim to enhance user understanding and efficiency in executing --- manuals/1.0/en/15.tech.md | 198 +++++++++++++++++++++----------------- 1 file changed, 108 insertions(+), 90 deletions(-) diff --git a/manuals/1.0/en/15.tech.md b/manuals/1.0/en/15.tech.md index ea951c74..3a236c7d 100644 --- a/manuals/1.0/en/15.tech.md +++ b/manuals/1.0/en/15.tech.md @@ -1,3 +1,5 @@ +Here is the English translation of the provided Japanese text: + --- layout: docs-en title: Technology @@ -12,72 +14,84 @@ This chapter explains the features and technical characteristics of BEAR.Sunday. > "Resources interconnected, like the web of life that binds all creatures." -BEAR.Sunday's ROA is an architecture for realizing RESTful APIs in the internal structure of web applications and is at the core of BEAR.Sunday's design principles. It is a hypermedia framework and also an object as a service. Like the Web, all data and functions are treated as resources and operated with specified interfaces such as GET/POST/PUT/DELETE. Resources are also interconnected. By providing hyperlinks to other resources, resources can provide not only information and functionality but also affordances. +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. -### Uniform Interface +### URI -Access to resources is done using HTTP methods (GET, POST, PUT, DELETE). These methods specify the operations that can be performed on resources and provide a common interface regardless of the type of resource. +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. + +### Uniform Interface -- GET: Retrieve the current state of a resource -- POST: Perform non-idempotent operations on a resource (such as creation) -- PUT: Perform idempotent operations on a resource (such as creation or update) -- DELETE: Delete a resource +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. -Here's the English translation: +- GET: Retrieves the current state of a resource +- POST: Performs a non-idempotent operation on a resource (e.g., creation) +- PUT: Performs an idempotent operation on a resource (e.g., creation or update) +- DELETE: Deletes a resource ## Hypermedia -In BEAR.Sunday's Resource-Oriented Architecture (ROA), each resource provides affordances (available operations and functions for the client) through hyperlinks. These links represent the operations available to the client and guide how to navigate within the application. This reduces the coupling between the client and the server, increasing the application's flexibility and extensibility. +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. -Hyperlinks not only represent relationships between resources but also function as a mechanism for embedding resources internally. This is similar to how HTML uses the IMG tag to embed image resources. In BEAR.Sunday, resources can be accessed as independent entities, and internal links can be used to create containment relationships between resources, allowing for declarative composition of the content's tree structure. +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. -BEAR.Sunday's hypermedia approach aligns with the principles of the Web, enhancing the flexibility and extensibility of applications. +BEAR.Sunday's hypermedia approach is a design that follows Web principles and enhances the flexibility and expandability of applications. ### 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, and the representation is for representing that value in various formats (JSON, XML, HTML, etc.). This separation makes domain logic and presentation logic loosely coupled, improving the maintainability and extensibility 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 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. ### Page Resources and App Resources -In BEAR.Sunday's ROA, resources are classified into page resources and app resources. +In BEAR.Sunday's ROA, resources are classified into two types: page resources and app resources. -- Page Resources: Resources that mainly represent HTML and are intended to be accessed from a web browser. They are resources that make up the user interface. -- App Resources: Resources that make up the backend of the application and mainly represent JSON or XML. They are intended to be accessed by other applications or services. +- 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. 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.). -By using BEAR.Sunday's ROA, scalable and loosely coupled applications that align with Web design principles can be built. Separating 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, improving application flexibility and extensibility. Hyperlinks also clarify relationships between resources, keep coupling between client and server low, and enhance resource self-description and API discoverability. +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. ### Differences from MVC -The ROA of BEAR.Sunday takes a different approach from the traditional MVC architecture. While MVC organizes an application into three components: model, view, and controller, in reality, the controller freely manipulates the model and view at runtime, literally controlling everything. +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. -In contrast, in BEAR.Sunday, a view is injected into a resource object, and the resource is ignorant of the view, and vice versa. The resource object does not perform any operations on the injected view and is unaware of which view is injected. The resource's methods are only concerned with the resource state, while the injected resource view renders the resource state to a string representation when the resource object is evaluated as a string. In this way, the resource and view are loosely coupled, with clear separation of concerns. +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. -Unlike the unrestricted relationship between the controller and model in MVC, there is a constraint in BEAR.Sunday where resources can contain other resources, declared using URIs. These resources can depend on other resources, forming a tree-like structure, similar to DI dependencies. Some other differences include: - -- BEAR.Sunday resources provide affordances, or possible operations, by declaring relations. Clients can dynamically manipulate resources using these hints, making them self-descriptive. -- HAL (Hypertext Application Language) is used for links to standardize the representation of links between resources. -- Unlike MVC models, they can be directly called from a diverse range of clients, including the console. -- There is no need to build HTML and API sites separately; the same resources can be used to build both simultaneously. +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: +- BEAR.Sunday resources provide possible operations (affordances) by declaring relations, making them 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. ## Dependency Injection (DI) > "Objects are injected from the interface, just as sun ray is injected when a window is opened." -Dependency Injection (DI) is a pattern that automatically resolves object creation and dependencies by the framework, lowering code coupling and improving testability and maintainability. BEAR.Sunday's DI uses [Ray.Di](https://github.com/ray-di/Ray.Di), an independent package that incorporates the design philosophy of Google's DI framework Guice and covers almost all of its features. +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. + +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". -What sets this framework's DI apart from other frameworks is that autowiring, which resolves dependencies based on rules without the user directly touching the container, is the default. Other features are as follows: +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. -* Context-dependent bindings change the application's behavior at compile time. -* Attribute-based configuration enhances code self-description. -* Qualifiers used to bind different implementations to the same interface also enhance code self-description. -* Ray.Di resolves dependencies at compile time, improving runtime performance. This differs from other DI containers that resolve dependencies at runtime. +### Binding by Context + +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. + +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. + +Other features include: + +* Attribute-based configuration enhances code self-descriptiveness. +* Using qualifiers to bind different implementations to the same interface also enhances code self-descriptiveness. +* 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. -* In addition to link bindings and instance bindings, various other bindings are supported, such as attribute bindings, untarget bindings, multi-bindings, constructor bindings, context bindings, and Null bindings. -* Provider bindings are also possible for lazy binding. -* Bindings can be grouped into modules, improving reusability. +* 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. +* Bindings can be grouped into modules for reuse. Ray.Di logo @@ -85,83 +99,86 @@ What sets this framework's DI apart from other frameworks is that autowiring, wh > "Aspects wrap your objects, like a gift wrap enhances a present." -Aspect Oriented Programming (AOP) is a pattern that separates core concerns such as business logic from cross-cutting concerns such as logging and caching, enabling flexible applications. BEAR.Sunday's AOP uses Ray.Aop, an independent package, and declaratively binds cross-cutting processing by attaching PHP attributes to classes and methods. +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. -AOP is one of the most misunderstood technologies. Its purpose is not to violate constraints and break order, but to complement areas where object orientation struggles, such as exploratory feature assignment and separation of cross-cutting processing, and to create application-wide constraints, i.e., it is one of the paradigms that can be designed as constraints of an application framework. +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: -Other features of AOP are as follows: +* 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 to classes and methods that match search criteria such as class and method names. -* By using PHP attributes, cross-cutting processing can be described declaratively. -* Classes and methods that match search criteria can be dynamically changed. +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. - -## Event-Driven Content Strategy Based on ROA by Integration with Modern CDN +## Event-Driven Content Strategy Based on ROA with Integration of Modern CDN > "No volatility, just what users truly desire." -BEAR.Sunday realizes an advanced event-driven caching strategy by integrating with instant-purgeable CDNs such as Fastly, with Resource Oriented Architecture (ROA) at its core. This strategy invalidates CDN and server-side caches, as well as ETags (Entity Tags), immediately in response to resource state change events, rather than invalidating caches based on traditional TTL (Time to Live). +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. -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, realizing the Web's original distributed caching for dynamic content just like static content. In other words, it re-realizes the scalable and network-cost-reducing principle of distributed caching that the Web has had since the 1990s using modern technology. +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. ### Cache Invalidation by Semantic Methods -In BEAR.Sunday's ROA, each resource operation is given semantics (a semantic role). For example, the GET method retrieves a resource, and 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, the 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. +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. -### Visualization of Dependencies through Embedded Links -In ROA design, resources can include links to other resources, transparently showing resource dependencies to clients. By utilizing this link information, when cache invalidation is needed, it can be instantly determined which resources are affected, enabling efficient cache management. +### 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. ### Cache Key Generation by Argument Declaration -In BEAR.Sunday, resource method arguments are explicitly declared. This allows for generating unique cache keys based on resource state or request parameters. Cache key generation is an important mechanism for accurately identifying and invalidating specific caches when a resource's state changes. This avoids unnecessary cache deletion while quickly updating only the necessary parts. +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. -### Identity Verification and Quick Response with ETag -By setting ETags before the system boots, content identity 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. +### 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. -### Partial Updates with Donut Caching and ESI -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 for dynamically updating only the necessary parts without recaching the entire page, significantly improving performance and caching efficiency. +### 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. -Thus, BEAR.Sunday's integration with Fastly and ROA-based caching strategy not only realizes advanced distributed caching but also enhances application performance and improves fault tolerance. This allows users to experience consistent responsiveness and data consistency under any circumstances. +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. ## Ease of Testing -* Each resource is independent, and due to the stateless request nature of REST, testing is easy. -* Since resource state and representation are separated, only the resource state can be tested. -* API testing can be performed by following hypermedia links, and testing can be done with the same code in PHP and HTTP. +BEAR.Sunday allows for 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. +* 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. +* Resources embedded with `#[Embed]` embed resource requests, not values. The intention of what kind of resource to embed can be tested. ## Resource Validation -Resource representation is validated using JsonSchema to maintain resource consistency. Using standard schemas for validation allows for the use of external tools. +JsonSchema is used to validate resource representations and maintain resource consistency. Using standard schemas for validation enables the use of external tools. ## Stream Output -* By streaming resource representation, large-scale content that cannot be handled in memory can be output. -* Streams can be mixed with normal value assignments. +* Streaming output of resource representations allows outputting large-scale content that cannot be handled in memory. +* Streams can coexist with normal value assignments. ## Visualization and Debugging -* During development, resource scopes and tools are graphically displayed on HTML. -* Resource state can be checked on the web screen, and PHP code and HTML templates can be edited online and reflected in real-time. +* 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. ## Startup Acceleration -* Pre-compilation generates PHP code for dependency generation to achieve 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 is reused to speed up application startup. +* 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 -In BEAR.Sunday, managing the execution of SQL statements for interacting with the database is made easy by using PHP interfaces. It is possible to directly bind SQL execution objects to interfaces without implementing classes. This improves code reusability and enhances modularity. +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. ### 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 for efficient handling of date and time data. +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. ### Dependency Injection of Query Arguments -In BEAR.Sunday, it is also possible to inject dependencies into interfaces. This allows for dynamically supplying necessary objects and values to interfaces, enabling more flexible application design. By using dependency injection, code testing becomes easier, and low coupling can be maintained while achieving high cohesion. +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. -### AI and Tool-Assisted SQL Generation and Optimization -In BEAR.Sunday, it is also possible to inject dependencies into interfaces. This allows for dynamically supplying necessary objects and values to interfaces, enabling more flexible application design. By using dependency injection, code testing becomes easier, and low coupling can be maintained while achieving high cohesion. +### 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. -### Overall 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 problems. Also, since query modifications and feature extensions can be made directly, application maintenance and evolution proceed smoothly. +### 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. -* By preparing PHP interfaces and SQL, 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 an SQL date. +* 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. * Dependencies can be injected as arguments into PHP interfaces. ## API Documentation Generation @@ -170,17 +187,17 @@ API documentation is automatically generated from code. This maintains consisten ## Integration with Other Systems -* Integration with console applications allows for accessing from both web and command line without changing source code. -* Different applications can be executed concurrently within the same PHP runtime, and all resources can be accessed from an HTTP client. -* Local and remote BEAR.Sunday applications can be handled similarly, and BEAR.Thrift allows for integration with applications in other languages. +* 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. ## Standards Compliance * JSON format and www-form format are supported by default, and resource requests are interpreted according to the content type. * Semantic versioning is adopted to maintain backward compatibility. -* Errors are returned in the `vnd.error+json` media type format by default, including detailed error messages. -* ETags are used to invalidate caches when a resource's state changes. -* When caching, in addition to the `Cache-Control` HTTP header, HTTP headers such as `Ages`, `Last-Modified`, and `ETag` are added. +* By default, errors are returned in the `vnd.error+json` media type format, returning error messages including error details. +* 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. ## Object-Oriented Principles @@ -188,33 +205,34 @@ BEAR.Sunday emphasizes object-oriented principles to make applications maintaina ### Composition over Inheritance -Composition is recommended over inheritance classes. In general, directly calling parent class methods from child classes can potentially increase coupling between classes. From a design perspective, the only abstract class that requires inheritance at runtime is the `BEAR\Resource\ResourceObject` resource class, but its methods exist only to be used by other classes. 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 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. -### Everything Is Injected +### Everything is Injected -Framework classes do not reference "configuration files" or "debug constants" at runtime to determine behavior. Dependencies corresponding to behavior are injected. This means that to change the application's behavior, there is no need to change code; only the binding of the implementation of dependencies to the interface needs to be changed. APP_DEBUG or APP_MODE constants do not exist. There is no way to know which mode the software is running in after it starts, nor is there a need to know. +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. ### Root Object -In the world of DI, users avoid directly dealing with the injector (DI container) as much as possible. Instead, a single root object is generated at the application's entry point to start the application. In BEAR.Sunday's DI, there is virtually no operation of the DI container even at configuration time. The root object is large but a single variable, so it is reused across requests to realize an extremely optimized bootstrap. +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. ## Non-Destructive Backward Compatibility -BEAR.Sunday is designed with a focus on maintaining backward compatibility in the evolution of software. In modern software development, frequent breaking of backward compatibility and the associated burden of modifications and testing have become issues, but BEAR.Sunday aims to avoid this problem and has been successful. +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. -This does not 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 was designed to apply this spirit of the Web to application frameworks as well. +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. -BEAR.Sunday adopts semantic versioning to prevent the addition of new features or changes to existing features from affecting existing code. Deprecated code is given the "deprecated" attribute but is not removed and does not affect the behavior of existing code. Instead, new features are added, and evolution continues. +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. -In fact, many features have been added since the release of BEAR.Sunday in the PHP 5.4 era, 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. +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. -This design, which makes backward compatibility an absolute imperative, and the approach using semantic versioning enable this long-term compatibility. This allows developers to adopt BEAR.Sunday with confidence and benefit from the evolving ecosystem. +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. ## Code Quality -To provide high-quality code applications, the BEAR.Sunday framework itself maintains a high standard of code quality. +To deliver high-quality applications, the BEAR.Sunday framework itself maintains a high standard of code quality. -* The framework's code applies both the static analysis tools psalm and phpstan at the maximum level. +* The framework code applies the maximum level of both psalm and phpstan static analysis tools. * 100% test coverage is maintained. -* Type coverage is also nearly 100%. The use of mixed is minimized. -* It is principally an immutable system and is so clean that initialization is not required every time even in tests. It brings out the power of PHP's asynchronous communication engines like Swoole. +* 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. +