Download the PHP package icanboogie/operation without Composer

On this page you can find all versions of the php package icanboogie/operation. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package operation

Operation

Release Build Status Code Quality Code Coverage Packagist

Operations are feature rich controllers dedicated to a single task, which often is to create/update/delete records.

Preamble

Events in this document are often referenced as ICanBoogie\Operation::<event_type>, where <event_type> is the type of the event. For instance, ICanBoogie\Operation::rescue is an event of type rescue, fired on an instance of ICanBoogie\Operation. Now consider a SaveOperation class inheriting from ICanBoogie\Operation. The rescue event could also be fired on one of its instances, and an event hook could be attached to SaveOperation::rescue to rescue the operation.

Because ICanBoogie's event system is based on class hierarchy an event hook attached to SaveOperation::rescue is only invoked to rescue instances of SaveOperation and its subclasses, whereas an event hook attached to ICanBoogie\Operation::rescue is invoked to rescue instances of ICanBoogie\Operation and its subclasses, including SaveOperation.

Thus, when you see ICanBoogie\Operation::rescue read "the event type 'rescue' fired on an instance of the ICanBoogie\Operation subclass I want to listen to".

Please read the documentation of the icanboogie/event package for more details about the event system.

Operation

An instance of Operation represents an operation. Although the class provides many control methods and getters, the validation and processing of the operation must be implemented by subclasses, according to their design.

Controlling the operation

Before the operation can be validated and processed, controls are ran. The controls to run are defined by the operation. The following controls are implemented and can be extended:

The controls definition is obtained though the controls magic property:

The following events are fired during the process:

Validating the operation

The operation needs to be validated before it is processed. The validate() method is invoked to validate the operation. Errors should be collected in the provided $errors collection. The validation is considered failed if the method returns an empty value or errors are defined.

The following events are fired during the process:

Processing the operation

After the control and the validation, the operation is finally processed by invoking its process() method. The processing of the operation is considered failed if the method returns null or errors are defined.

The following events are fired during the process:

Handling failure

Exceptions thrown during the process (control/validation/processing) are caught and turned into Failure exceptions. The original exception is accessible using the getPrevious() method or the previous property. The response of the operation is updated with the exception code and message.

A Failure exception is also thrown in the response has a client or server error, in which case the exception is fired without a previous exception.

Note: Failed operations may be rescued by the dispatcher.

Forwarded operations

An operation is considered forwarded when the actual destination and operation name is defined using the request parameters Operation::DESTINATION and Operation::NAME. The URL of the request is irrelevant to forwarded operations, moreover whether they succeed or fail the dispatch process simply continues. For instance, this allows forms to be posted to their own view URL (not the URL of the operation) and displayed again if an error occurs.

Note: Successful responses with a location are NOT discarded, they will redirect the request.

Note: This feature is currently a foundation for the icanboogie/module package and its really that package who handles forwarded operations. This may change is the future.

Response

The response of the operation is represented by a Response instance. The value returned by the process() method is set to its rc property. The operation is considered failed if its value is null, in which case the status of the operation is set to "400 Operation failed".

Response location

The Location header is used to ask the browser to load a different web page. This is often used to redirect the user when an operation has been performed e.g. creating/deleting a resource. The location property of the response is used to set that header.

Response location and XHR

Redirecting a XHR is not a desirable behavior because although we might want to redirect the user, we still need to get the result of our request first. In that case, the value of the location property is moved to the redirect_to field and the location property is set to null. Thus, the browser redirection is disabled, the response is returned and it's up to the developer to choose if he should honor the redirection or not.

Dispatcher

The package provides an HTTP dispatcher to dispatch operations. It should be placed at the top of the dispatcher chain, before any routing. The dispatcher tries to create an Operation instance from the specified request, and returns immediately if it fails.

Handling of the operation response

The dispatcher discards responses from forwarded operations unless the request is an XHR or the response has a location. Remember that failed operations throw a Failure exception, which can be rescued.

Rescuing failed operations

If an exception is thrown during the dispatch of the operation, the dispatcher tries to rescue it using the following steps:

  1. The ICanBoogie\Operation::rescue event of class RescueEvent is fired. Event hooks attached to this event may replace the exception or provide a response. If a response is provided it is returned.
  2. Otherwise, if the exception is not an instance of Failure the exception is re-thrown.
  3. Otherwise, if the request is an XHR the response of the operation is returned.
  4. Otherwise, if the operation was forwarded the exception message is logged as an error and the method returns.
  5. Otherwise, the exception is re-thrown.

In summary, a failed operation is rescued if a response is provided during the ICanBoogie\Operation::rescue event, or later if the request is an XHR. Although the rescue of an operation might be successful, the returned response can be an error response.

Note: If the operation is forwarded and the operation could not be rescued the request dispatching process will simply continue.

Defining operations

Defining operations as routes

Because operations are controllers, they may be defined in the same fashion.

The following example demonstrates how the module Nodes defines routes to set/unset the is_online property:

The class of the operation is defined as the controller of the route. Notice how the request method is used for the same route to distinguish the operation type.

The param_translation_list array is used to define how params captured from the pathinfo should be translated before the operation is executed. This handy feature allow routes to be formatted from records, while providing mapping to operation key features.

Exceptions

The exception classes defined by the package implement the ICanBoogie\Operation\Exception interface so that they can easily be identified:

The following exceptions are defined:


Requirements

The package requires PHP 7.2 or later.

Installation

Documentation

The package is documented as part of the [ICanBoogie][] framework documentation. You can generate the documentation for the package and its dependencies with the make doc command. The documentation is generated in the build/docs directory. ApiGen is required. The directory can later be cleaned with the make clean command.

Testing

Run make test-container to create and log into the test container, then run make test to run the test suite. Alternatively, run make test-coverage to run the test suite with test coverage. Open build/coverage/index.html to see the breakdown of the code coverage.

License

icanboogie/operation is released under the New BSD License.


All versions of operation with dependencies

PHP Build Version
Package Version
Requires php Version >=7.2
icanboogie/bind-routing Version ^5.0
icanboogie/errors Version ^2.0
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package icanboogie/operation contains the following files

Loading the files please wait ....