Merge pull request #290 from niden-code/5.9.x

reworded security and acl; reformat for warnings

Author: niden

docs/acl.md

@@ -38,7 +38,7 @@ In this example, a [Role][acl-role] indicates who needs access to a specific [Co
 Using the [Phalcon\Acl][acl-acl] component, you can establish associations between these [Roles][acl-role] and [Components][acl-component], enhancing the application's security by allowing only specific roles to access designated components.
 
 ## Activation
-[Phalcon\Acl][acl-acl] relies on adapters to manage roles and components. Presently, the only available adapter is [Phalcon\Acl\Adapter\Memory][acl-adapter-memory]. While using the memory adapter significantly enhances ACL access speed, it comes with the trade-off of non-persistent memory. Therefore, developers need to implement a storage strategy for ACL data to avoid regenerating the ACL at every request. This is particularly crucial for large ACLs stored in a database or file system.
+[Phalcon\Acl][acl-acl] uses adapters to manage roles and components. Currently the built-in adapter is [Phalcon\Acl\Adapter\Memory][acl-adapter-memory]. The memory adapter is fast but non-persistent, so you should persist the ACL (cache or file) in production to avoid rebuilding it on every request.
 
 The [Phalcon\Acl][acl-acl] constructor takes an adapter as its first parameter for retrieving information related to the control list.
 
@@ -110,7 +110,7 @@ $acl->addRole('guest');
 ```
 
 ## Adding Components
-A [Component][acl-component] in the context of Phalcon\Acl represents an area of the application where access is controlled. In an MVC application, this typically corresponds to a Controller. Although it is not mandatory, you can use the [Phalcon\Acl\Component][acl-component] class to define components in the application. It is important to add related actions to a component so that the ACL understands what it should control.
+A [Component][acl-component] in the context of Phalcon\Acl represents an area of the application where access is controlled. In an MVC application, this typically corresponds to a Controller. Although not required, you can use the [Phalcon\Acl\Component][acl-component] class to define components in the application. It is important to add related actions to a component so that the ACL understands what it should control.
 
 There are two ways to add components to our list:
 
@@ -225,6 +225,8 @@ $acl->allow('manager', 'admin', 'dashboard');
 $acl->allow('manager', 'reports', ['list', 'add']);
 $acl->allow('accounting', 'reports', '*');
 $acl->allow('*', 'session', '*');
+$acl->allow('*', '*', 'view');
+$acl->deny('guest', '*', 'view');
 ```
 
 In the above example:
@@ -234,13 +236,10 @@ In the above example:
 * `$acl->allow('*', 'session', '*');`: Wildcards can be used for mass matching roles, components, or actions. This line allows every role to access every action in the `session` component.
 * `$acl->allow('*', '*', 'view');`: This line gives access to the `view` action to every role. In MVC terms, it allows any role to access any controller that exposes a `viewAction`.
 * `$acl->deny('guest', '*', 'view');`: For the `guest` role, deny access to all components with the `view` action. Despite the default access level being `Acl\Enum::DENY`, this line specifically denies the `view` action to all roles and components. It ensures that the `guest` role only has access to the `session` component and the `login` and `logout` actions since guests are not logged into the application.
-* `$acl->allow('*', '*', 'view');`: This line gives access to the `view` action to every role. However, the following line excludes the `guest` role from that access:
-
-```php
-$acl->deny('guest', '*', 'view');
-```
+* `$acl->allow('*', '*', 'view');`: This line gives access to the `view` action to every role.
+* `$acl->deny('guest', '*', 'view');`: This line excludes the `guest` role from the `view` access:
 
-!!! danger "NOTE"
+!!! danger "DANGER"
 
     Please be **VERY** careful when using the `*` wildcard. It is very easy to make a mistake and the wildcard, although it seems convenient, it may allow users to access areas of your application that they are not supposed to. The best way to be 100% sure is to write tests specifically to test the permissions and the ACL. These can be done in the `unit` test suite by instantiating the component and then checking the `isAllowed()` if it is `true` or `false`.
 
@@ -665,7 +664,7 @@ if ($acl->isAllowed('manager', 'admin', 'dashboard')) {
 }
 ```
 
-It is a good practice to not use serialization of the ACL during development to ensure that your ACL is rebuilt with every request, while other adapters or means of serializing and storing the ACL in production.
+It is a good practice to not serialize the ACL during development to ensure that your ACL is rebuilt with every request, while other adapters or means of serializing and storing the ACL in production.
 
 ## Events
 [Phalcon\Acl][acl-acl] can work in conjunction with the [Events Manager][events] if present, to fire events to your application. Events are triggered using the type `acl`. Events that return `false` can stop the active role. The following events are available:

docs/api/phalcon_mvc.md

@@ -2669,7 +2669,7 @@ $invoice->inv_total = 120;
 $invoice->update();
 ```
 
-!!! warning "NOTE"
+!!! warning "WARNING"
 
     When retrieving the record with `findFirst()`, you need to get the full
     object back (no `columns` definition) but also retrieve it using the
@@ -14640,5 +14640,3 @@ Appends template before controller layout
 public function start();
 ```
 Starts rendering process enabling the output buffering
-
-

docs/application-micro.md

@@ -36,7 +36,7 @@ $container = new Di();
 $app       = new Micro($container);
 ```
 
-!!! warning "NOTE"
+!!! warning "WARNING"
 
     Starting from Phalcon v5.3.0, the `Micro` object is no longer automatically registered in the dependency injection container with the name `application`. Developers are required to manage the application instance explicitly.
 
@@ -308,7 +308,7 @@ Defining routes in a [Phalcon\Mvc\Micro][mvc-micro] application is straightforwa
 ### Activation
 Routing is managed by the [Phalcon\Mvc\Router][mvc-router] object.
 
-!!! warning "NOTE"
+!!! warning "WARNING"
 
     Routes must always start with `/`
 
@@ -994,7 +994,7 @@ $invoices->get('/delete/{id}', 'deleteAction');
 $app->mount($invoices);
 ```
 
-!!! warning "NOTE"
+!!! warning "WARNING"
 
     The name that we bind each route has a suffix of `Action`. This is not necessary, your method can be called anything you like.
 
@@ -1655,7 +1655,7 @@ Middleware can be attached to a Micro application in three different events:
 | `after`  | After the handler has been executed            |
 | `finish` | After the response has been sent to the caller |
 
-!!! warning "NOTE"
+!!! warning "WARNING"
 
     Multiple middleware classes can be attached to each of the above events, and they will be executed sequentially when the relevant event fires.
 
@@ -2199,7 +2199,7 @@ class RequestMiddleware implements MiddlewareInterface
 
 This middleware is responsible for manipulating our response and sending it back to the caller as a JSON string. Therefore, we need to attach it to the `after` event of our Micro application.
 
-!!! warning "NOTE"
+!!! warning "WARNING"
 
     We are using the `call` method for this middleware since we have nearly executed the whole request cycle.
 
@@ -2246,7 +2246,7 @@ class ResponseMiddleware implements MiddlewareInterface
 
 Models can be utilized in Micro applications by instructing the application on how to find the relevant classes through an autoloader.
 
-!!! warning "NOTE"
+!!! warning "WARNING"
 
     The relevant `db` service must be registered in your DI container.
 
@@ -2364,7 +2364,7 @@ $app->get(
 );
 ```
 
-!!! warning "NOTE"
+!!! warning "WARNING"
 
     The above example uses the [Phalcon\Mvc\View\Simple][mvc-view-simple] component, which uses relative paths instead of controllers and actions. You can use the [Phalcon\Mvc\View][mvc-view] component instead, but to do so, you will need to change the parameters passed to `render()`.
 

docs/application.md

@@ -27,7 +27,7 @@ try {
 }
 ```
 
-!!! warning "NOTE"
+!!! warning "WARNING"
 
     `handle()` accepts a URI and will not operate without it. You can pass the `$_SERVER["REQUEST_URI"]` as a parameter
 

docs/assets.md

@@ -736,7 +736,7 @@ The output will include the file modification time in the URL:
 <link rel="stylesheet" href="css/bootstrap.css?ver=1558392141">
 ```
 
-!!! warning "NOTE"
+!!! warning "WARNING"
 
     Using the auto version feature is not recommended for production environments due to unnecessary file system read operations.
 

docs/autoload.md

@@ -1,7 +1,7 @@
 # Loader
 - - -
 
-!!! warning "NOTE"
+!!! warning "WARNING"
 
     The `Phalcon\Autoload\Loader` class has been renamed `Phalcon\Autoload\Loader`. The functionality remains the same.
 
@@ -38,7 +38,7 @@ $loader->register();
 
 You can always call the `isRegistered()` method to check if your autoloader is registered or not.
 
-!!! warning "NOTE"
+!!! warning "WARNING"
 
     If there is an error in registering the autoloader, the component will throw an exception.
 

docs/config.md

@@ -256,7 +256,7 @@ echo config('app-name', 'default', '-');     // PHALCON
 echo config('app-unknown', 'default', '-');  // default
 ```
 
-!!! warning "NOTE"
+!!! warning "WARNING"
 
     If the keys from your data contain special characters such as `.` or `-`, and you choose to use the same character for your delimiter when using the `path()` method, you will not get the desired results back, since `path()` will interpret the delimiter as a new nested level.
 

docs/contributions.md

@@ -17,11 +17,11 @@ When you create a pull request, we have a handy template to help you describe wh
 * put on hold, if a discussion is necessary (community, core team etc.)
 * rejected
 
-!!! warning "NOTE"
+!!! warning "WARNING"
 
     If your pull request is a new feature, it is best to discuss it with the core team first, to ensure that it will align with the evolution of the framework.
 
-!!! danger "NOTE"
+!!! danger "DANGER"
 
     Please make sure that the target branch that you send your pull request is correct and that you have already rebased your code. Pull requests to the **master** branch are not allowed
 
@@ -35,7 +35,7 @@ We have removed the translations from v5.5.x onward. There was not that much tra
 
 ## Questions and Support
 
-!!! danger "NOTE"
+!!! danger "DANGER"
 
     We only accept bug reports, new feature requests and pull requests in GitHub. For questions regarding the usage of the framework or support requests please visit the [official discussions page][phalcon-discussions] or our [Discord][phalcon-discord] server.
 

docs/controllers.md

@@ -92,11 +92,11 @@ class InvoicesController extends Controller
 }
 ```
 
-!!! warning "NOTE"
+!!! warning "WARNING"
 
     The use of the `__construct()` method is not recommended.
 
-!!! warning "NOTE"
+!!! warning "WARNING"
 
     The `initialize()` method is only called if the `beforeExecuteRoute` event has been executed successfully. This is to ensure that if you have authorization checking code in the event, `initialize` will never be invoked
 
@@ -116,7 +116,7 @@ class InvoicesController extends Controller
 }
 ```
 
-!!! warning "NOTE"
+!!! warning "WARNING"
 
     Note that `onConstruct()` is executed even if the action to be executed does not exist in the controller or the user does not have access to it (assuming custom access control is implemented in the application).
 
@@ -245,7 +245,7 @@ class InvoicesController extends Controller
 }
 ```
 
-!!! warning "NOTE"
+!!! warning "WARNING"
 
     You will need to add additional code to ensure that the data passed is of the correct type and either use the default value or have a correct value. If not, you will end up with errors.
 
@@ -626,4 +626,4 @@ $container->set(
 [application]: application.md
 [autoload]: autoload.md
 [routing]: routing.md
-[views]: views.md
+[views]: views.md

docs/datamapper.md

@@ -5,7 +5,7 @@
 
     These components have been heavily influenced by [Aura PHP][auraphp] and [Atlas PHP][atlasphp] 
 
-!!! warning "NOTE"
+!!! warning "WARNING"
 
     The full implementation of a DataMapper is not yet complete. There are however a few components that can be used in any project, such as the `Connection` and `Query/Select` 
 
@@ -2461,7 +2461,7 @@ $update->perform();
 //      inv_status_flag = :inv_status_flag
 ```
 
-!!! warning "NOTE"
+!!! warning "WARNING"
 
     Using the `columns()` method you are not able to set the type of each parameter.