├── CONTRIBUTING.md ├── LICENSE-CC.md ├── LICENSE-MIT.md ├── LICENSE.md ├── README-ES.md ├── README.md ├── accepted ├── PSR-0.md ├── PSR-1-basic-coding-standard.md ├── PSR-2-coding-style-guide-meta.md ├── PSR-2-coding-style-guide.md ├── PSR-3-logger-interface.md ├── PSR-4-autoloader-examples.md ├── PSR-4-autoloader-meta.md ├── PSR-4-autoloader.md ├── PSR-7-http-message-meta.md ├── PSR-7-http-message.md ├── es │ ├── PSR-0.md │ ├── PSR-1-codificacion-estandar-basica.md │ ├── PSR-2-guia-de-estilo-de-codificacion.md │ └── PSR-3-interfaz-de-logger.md ├── fr │ ├── PSR-0.md │ ├── PSR-1-basic-coding-standard.md │ ├── PSR-2-coding-style-guide.md │ ├── PSR-3-logger-interface.md │ └── PSR-4-autoloader.md ├── it │ ├── PSR-0.md │ ├── PSR-1-basic-coding-standard.md │ ├── PSR-2-coding-style-guide.md │ ├── PSR-3-logger-interface.md │ ├── PSR-4-autoloader-examples.md │ ├── PSR-4-autoloader-meta.md │ └── PSR-4-autoloader.md ├── pl │ ├── PSR-0.md │ ├── PSR-1-podstawowe-standardy-kodowania.md │ ├── PSR-2-przewodnik-po-standardach-formatowania.md │ ├── PSR-3-interfejs-dziennika.md │ └── PSR-4-autoloader.md ├── pt-BR │ ├── PSR-0.md │ ├── PSR-1-padrao-basico-de-codificacao.md │ ├── PSR-2-guia-de-estilo-de-codificacao-meta.md │ └── PSR-2-guia-de-estilo-de-codificacao.md ├── ru │ ├── PSR-0.md │ ├── PSR-1-basic-coding-standard.md │ ├── PSR-2-coding-style-guide-meta.md │ ├── PSR-2-coding-style-guide.md │ ├── PSR-4-autoloader-examples.md │ ├── PSR-4-autoloader-meta.md │ └── PSR-4-autoloader.md └── sl │ ├── PSR-0.md │ ├── PSR-1-basic-coding-standard.md │ ├── PSR-2-coding-style-guide-meta.md │ ├── PSR-2-coding-style-guide.md │ ├── PSR-3-logger-interface.md │ ├── PSR-4-autoloader-examples.md │ ├── PSR-4-autoloader-meta.md │ ├── PSR-4-autoloader.md │ ├── PSR-7-http-message-meta.md │ └── PSR-7-http-message.md ├── bylaws ├── 001-voting-protocol.md ├── 002-psr-naming-conventions.md ├── 003-membership.md ├── 004-psr-workflow.md ├── 005-licensing-policies.md ├── 006-psr-amendments.md ├── es │ ├── 001-protocolo-de-votacion.md │ └── 002-convenciones-de-nombres-psr.md └── sl │ ├── 001-voting-protocol.md │ ├── 002-psr-naming-conventions.md │ ├── 003-membership.md │ ├── 004-psr-workflow.md │ ├── 005-licensing-policies.md │ └── 006-psr-amendments.md ├── index.md └── proposed ├── .placeholder ├── cache-meta.md ├── cache.md ├── container-meta.md ├── container.md ├── event-loop-meta.md ├── event-loop.md ├── extended-coding-style-guide-meta.md ├── extended-coding-style-guide.md ├── images ├── interoperating_containers.png ├── priority.png └── side_by_side_containers.png ├── psr-8-hug ├── PSR-8-hug-meta.md └── psr-8-hug.md ├── security-disclosure-publication-meta.md ├── security-disclosure-publication.md ├── security-disclosure-publication.xsd ├── security-reporting-process-meta.md └── security-reporting-process.md /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing to the PHP-FIG 2 | 3 | Anybody who subscribes to the Google Group, is part of the PHP-FIG. As soon as 4 | you subscribe to the [mailing list](http://groups.google.com/group/php-fig/) 5 | and/or join the [IRC channel](http://www.php-fig.org/irc/) you are a PHP-FIG 6 | Community Member, who can influence standards, make suggestions, give feedback, 7 | etc. Only PHP-FIG Voting Members can start or participate in votes, but the 8 | discussion and formation stages involve everyone. 9 | 10 | See the [PHP-FIG FAQ](http://www.php-fig.org/faq/) for more information. 11 | 12 | # Licensing 13 | 14 | By contributing code you agree to license your contribution under the MIT 15 | license. 16 | 17 | By contributing documentation, examples, or any other non-code assets you agree 18 | to license your contribution under the CC BY 3.0 license. Attribution shall be 19 | given according to the current bylaws of this group. 20 | -------------------------------------------------------------------------------- /LICENSE-MIT.md: -------------------------------------------------------------------------------- 1 | Copyright (c) 2013 PHP Framework Interop Group 2 | 3 | Permission is hereby granted, free of charge, to any person obtaining a copy 4 | of this software and associated documentation files (the "Software"), to deal 5 | in the Software without restriction, including without limitation the rights 6 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 7 | copies of the Software, and to permit persons to whom the Software is 8 | furnished to do so, subject to the following conditions: 9 | 10 | The above copyright notice and this permission notice shall be included in 11 | all copies or substantial portions of the Software. 12 | 13 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 14 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 15 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 16 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 17 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 18 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 19 | THE SOFTWARE. 20 | 21 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | # License 2 | 3 | Unless stated otherwise, all content is licensed under the Creative Commons 4 | Attribution License and code licensed under the MIT License. 5 | 6 | Copies of all licenses are included in this project's root directory. -------------------------------------------------------------------------------- /README-ES.md: -------------------------------------------------------------------------------- 1 | Grupo de interoperatibilidad para Frameworks PHP 2 | ================================================ 3 | 4 | La idea del grupo es hablar sobre los puntos en común entre los diferentes proyectos y encontrar formas de trabajar juntos. Nuestro destino principal son el resto de miembros del grupo, pero somos muy conscientes de que el resto de la comunidad PHP nos está observando. Si otros desarrolladores quieren adoptar lo que estamos proponiendo son bienvenidos a hacerlo, pero no es el objetivo del grupo. 5 | 6 | Propuesta de una recomendación de estándares 7 | -------------------------------------------- 8 | 9 | Para proponer una recomendación de estándar (PSR en inglés "Proposing a Standards Recommendation"): 10 | 11 | - haga un fork de este repositorio, cree una rama, cambie a esa rama, añada la propuesta en la carpeta `proposed/`, haga "push" de la rama a Github y envíenos un "pull request"; o, 12 | 13 | - cree un nuevo ticket para iniciar una discusión en Github; o, 14 | 15 | - inicie una conversación en nuestra [lista de correo][]. 16 | 17 | [lista de correo]: http://groups.google.com/group/php-fig/ 18 | 19 | 20 | Solicitud de membresía 21 | ---------------------- 22 | 23 | **No** necesita ser un miembro con derecho a voto para participar en las discusiones en la [lista de correo][]. 24 | 25 | Para convertirse en un miembro con capacidad de voto, debe enviar un email a la [lista de correo][]. 26 | 27 | - El asunto del mensaje debe ser (en inglés): `Membership Request: {$your_name} ({$project_name})` 28 | 29 | - En el cuerpo del mensaje, incluya su nombre, el nombre del proyecto (y enlace) al que representa y otros detalles que crea que puedan ser relevantes. 30 | 31 | Los miembros actuales votarán su aceptación. 32 | 33 | No combine solicitudes para ser miembro en un solo hilo; por favor, una petición por hilo. 34 | 35 | 36 | Miembros con derecho a voto 37 | --------------------------- 38 | 39 | La lista actalizada de miembros con derecho a voto está disponible en el [sitio web del proyecto][]. 40 | 41 | [sitio web del proyecto]: http://www.php-fig.org/ 42 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | PHP Framework Interoperability Group 2 | ==================================== 3 | 4 | The idea behind the group is for project representatives to talk about the 5 | commonalities between our projects and find ways we can work together. Our main 6 | audience is each other, but we’re very aware that the rest of the PHP community 7 | is watching. If other folks want to adopt what we’re doing they are welcome to 8 | do so, but that is not the aim. 9 | 10 | 11 | Proposing a Standard Recommendation 12 | ------------------------------------ 13 | 14 | To propose a PHP Standard Recommendation (PSR): 15 | 16 | - fork this repo, create a branch, checkout that branch, add the PSR in 17 | `proposed/`, push the branch to Github, and send a pull request; or, 18 | 19 | - create a ticket to start a discussion on Github; or, 20 | 21 | - start a conversation on the [mailing list][]. 22 | 23 | [mailing list]: http://groups.google.com/group/php-fig/ 24 | 25 | 26 | Requesting Membership 27 | --------------------- 28 | 29 | You **do not** need to be a voting member to participate in discussion on 30 | the [mailing list][]. 31 | 32 | To become a voting member, you must send an email to the [mailing list][]. 33 | 34 | - The subject line should read: `Membership Request: {$your_name} ({$project_name})` 35 | 36 | - The body should include your name, the name of (and link to) the project you 37 | represent, and other details you feel are relevant. 38 | 39 | - Current members will vote on your request. 40 | 41 | Do not combine separate membership requests in a single thread; one request 42 | per thread, please. 43 | 44 | 45 | Voting Members 46 | -------------- 47 | 48 | The current list of voting members is available on the [project website][]. 49 | 50 | [project website]: http://www.php-fig.org/ 51 | -------------------------------------------------------------------------------- /accepted/PSR-0.md: -------------------------------------------------------------------------------- 1 | Autoloading Standard 2 | ==================== 3 | 4 | > **Deprecated** - As of 2014-10-21 PSR-0 has been marked as deprecated. [PSR-4] is now recommended 5 | as an alternative. 6 | 7 | [PSR-4]: http://www.php-fig.org/psr/psr-4/ 8 | 9 | The following describes the mandatory requirements that must be adhered 10 | to for autoloader interoperability. 11 | 12 | Mandatory 13 | --------- 14 | 15 | * A fully-qualified namespace and class must have the following 16 | structure `\\(\)*` 17 | * Each namespace must have a top-level namespace ("Vendor Name"). 18 | * Each namespace can have as many sub-namespaces as it wishes. 19 | * Each namespace separator is converted to a `DIRECTORY_SEPARATOR` when 20 | loading from the file system. 21 | * Each `_` character in the CLASS NAME is converted to a 22 | `DIRECTORY_SEPARATOR`. The `_` character has no special meaning in the 23 | namespace. 24 | * The fully-qualified namespace and class is suffixed with `.php` when 25 | loading from the file system. 26 | * Alphabetic characters in vendor names, namespaces, and class names may 27 | be of any combination of lower case and upper case. 28 | 29 | Examples 30 | -------- 31 | 32 | * `\Doctrine\Common\IsolatedClassLoader` => `/path/to/project/lib/vendor/Doctrine/Common/IsolatedClassLoader.php` 33 | * `\Symfony\Core\Request` => `/path/to/project/lib/vendor/Symfony/Core/Request.php` 34 | * `\Zend\Acl` => `/path/to/project/lib/vendor/Zend/Acl.php` 35 | * `\Zend\Mail\Message` => `/path/to/project/lib/vendor/Zend/Mail/Message.php` 36 | 37 | Underscores in Namespaces and Class Names 38 | ----------------------------------------- 39 | 40 | * `\namespace\package\Class_Name` => `/path/to/project/lib/vendor/namespace/package/Class/Name.php` 41 | * `\namespace\package_name\Class_Name` => `/path/to/project/lib/vendor/namespace/package_name/Class/Name.php` 42 | 43 | The standards we set here should be the lowest common denominator for 44 | painless autoloader interoperability. You can test that you are 45 | following these standards by utilizing this sample SplClassLoader 46 | implementation which is able to load PHP 5.3 classes. 47 | 48 | Example Implementation 49 | ---------------------- 50 | 51 | Below is an example function to simply demonstrate how the above 52 | proposed standards are autoloaded. 53 | 54 | ```php 55 | ` tags or the short-echo `` tags; it 43 | MUST NOT use the other tag variations. 44 | 45 | ### 2.2. Character Encoding 46 | 47 | PHP code MUST use only UTF-8 without BOM. 48 | 49 | ### 2.3. Side Effects 50 | 51 | A file SHOULD declare new symbols (classes, functions, constants, 52 | etc.) and cause no other side effects, or it SHOULD execute logic with side 53 | effects, but SHOULD NOT do both. 54 | 55 | The phrase "side effects" means execution of logic not directly related to 56 | declaring classes, functions, constants, etc., *merely from including the 57 | file*. 58 | 59 | "Side effects" include but are not limited to: generating output, explicit 60 | use of `require` or `include`, connecting to external services, modifying ini 61 | settings, emitting errors or exceptions, modifying global or static variables, 62 | reading from or writing to a file, and so on. 63 | 64 | The following is an example of a file with both declarations and side effects; 65 | i.e, an example of what to avoid: 66 | 67 | ```php 68 | \n"; 77 | 78 | // declaration 79 | function foo() 80 | { 81 | // function body 82 | } 83 | ``` 84 | 85 | The following example is of a file that contains declarations without side 86 | effects; i.e., an example of what to emulate: 87 | 88 | ```php 89 | get('/hello/{name}', function ($name) use ($app) { 39 | return 'Hello '.$app->escape($name); 40 | }); 41 | ``` 42 | 43 | ### 3.2 - Extending Multiple Interfaces (10/17/2013) 44 | 45 | When extending multiple interfaces, the list of `extends` should be treated the same as a list 46 | of `implements`, as declared in Section 4.1. 47 | 48 | -------------------------------------------------------------------------------- /accepted/PSR-3-logger-interface.md: -------------------------------------------------------------------------------- 1 | Logger Interface 2 | ================ 3 | 4 | This document describes a common interface for logging libraries. 5 | 6 | The main goal is to allow libraries to receive a `Psr\Log\LoggerInterface` 7 | object and write logs to it in a simple and universal way. Frameworks 8 | and CMSs that have custom needs MAY extend the interface for their own 9 | purpose, but SHOULD remain compatible with this document. This ensures 10 | that the third-party libraries an application uses can write to the 11 | centralized application logs. 12 | 13 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", 14 | "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be 15 | interpreted as described in [RFC 2119][]. 16 | 17 | The word `implementor` in this document is to be interpreted as someone 18 | implementing the `LoggerInterface` in a log-related library or framework. 19 | Users of loggers are referred to as `user`. 20 | 21 | [RFC 2119]: http://tools.ietf.org/html/rfc2119 22 | 23 | 1. Specification 24 | ----------------- 25 | 26 | ### 1.1 Basics 27 | 28 | - The `LoggerInterface` exposes eight methods to write logs to the eight 29 | [RFC 5424][] levels (debug, info, notice, warning, error, critical, alert, 30 | emergency). 31 | 32 | - A ninth method, `log`, accepts a log level as first argument. Calling this 33 | method with one of the log level constants MUST have the same result as 34 | calling the level-specific method. Calling this method with a level not 35 | defined by this specification MUST throw a `Psr\Log\InvalidArgumentException` 36 | if the implementation does not know about the level. Users SHOULD NOT use a 37 | custom level without knowing for sure the current implementation supports it. 38 | 39 | [RFC 5424]: http://tools.ietf.org/html/rfc5424 40 | 41 | ### 1.2 Message 42 | 43 | - Every method accepts a string as the message, or an object with a 44 | `__toString()` method. Implementors MAY have special handling for the passed 45 | objects. If that is not the case, implementors MUST cast it to a string. 46 | 47 | - The message MAY contain placeholders which implementors MAY replace with 48 | values from the context array. 49 | 50 | Placeholder names MUST correspond to keys in the context array. 51 | 52 | Placeholder names MUST be delimited with a single opening brace `{` and 53 | a single closing brace `}`. There MUST NOT be any whitespace between the 54 | delimiters and the placeholder name. 55 | 56 | Placeholder names SHOULD be composed only of the characters `A-Z`, `a-z`, 57 | `0-9`, underscore `_`, and period `.`. The use of other characters is 58 | reserved for future modifications of the placeholders specification. 59 | 60 | Implementors MAY use placeholders to implement various escaping strategies 61 | and translate logs for display. Users SHOULD NOT pre-escape placeholder 62 | values since they can not know in which context the data will be displayed. 63 | 64 | The following is an example implementation of placeholder interpolation 65 | provided for reference purposes only: 66 | 67 | ```php 68 | /** 69 | * Interpolates context values into the message placeholders. 70 | */ 71 | function interpolate($message, array $context = array()) 72 | { 73 | // build a replacement array with braces around the context keys 74 | $replace = array(); 75 | foreach ($context as $key => $val) { 76 | $replace['{' . $key . '}'] = $val; 77 | } 78 | 79 | // interpolate replacement values into the message and return 80 | return strtr($message, $replace); 81 | } 82 | 83 | // a message with brace-delimited placeholder names 84 | $message = "User {username} created"; 85 | 86 | // a context array of placeholder names => replacement values 87 | $context = array('username' => 'bolivar'); 88 | 89 | // echoes "User bolivar created" 90 | echo interpolate($message, $context); 91 | ``` 92 | 93 | ### 1.3 Context 94 | 95 | - Every method accepts an array as context data. This is meant to hold any 96 | extraneous information that does not fit well in a string. The array can 97 | contain anything. Implementors MUST ensure they treat context data with 98 | as much lenience as possible. A given value in the context MUST NOT throw 99 | an exception nor raise any php error, warning or notice. 100 | 101 | - If an `Exception` object is passed in the context data, it MUST be in the 102 | `'exception'` key. Logging exceptions is a common pattern and this allows 103 | implementors to extract a stack trace from the exception when the log 104 | backend supports it. Implementors MUST still verify that the `'exception'` 105 | key is actually an `Exception` before using it as such, as it MAY contain 106 | anything. 107 | 108 | ### 1.4 Helper classes and interfaces 109 | 110 | - The `Psr\Log\AbstractLogger` class lets you implement the `LoggerInterface` 111 | very easily by extending it and implementing the generic `log` method. 112 | The other eight methods are forwarding the message and context to it. 113 | 114 | - Similarly, using the `Psr\Log\LoggerTrait` only requires you to 115 | implement the generic `log` method. Note that since traits can not implement 116 | interfaces, in this case you still have to implement `LoggerInterface`. 117 | 118 | - The `Psr\Log\NullLogger` is provided together with the interface. It MAY be 119 | used by users of the interface to provide a fall-back "black hole" 120 | implementation if no logger is given to them. However conditional logging 121 | may be a better approach if context data creation is expensive. 122 | 123 | - The `Psr\Log\LoggerAwareInterface` only contains a 124 | `setLogger(LoggerInterface $logger)` method and can be used by frameworks to 125 | auto-wire arbitrary instances with a logger. 126 | 127 | - The `Psr\Log\LoggerAwareTrait` trait can be used to implement the equivalent 128 | interface easily in any class. It gives you access to `$this->logger`. 129 | 130 | - The `Psr\Log\LogLevel` class holds constants for the eight log levels. 131 | 132 | 2. Package 133 | ---------- 134 | 135 | The interfaces and classes described as well as relevant exception classes 136 | and a test suite to verify your implementation is provided as part of the 137 | [psr/log](https://packagist.org/packages/psr/log) package. 138 | 139 | 3. `Psr\Log\LoggerInterface` 140 | ---------------------------- 141 | 142 | ```php 143 | (\)*\ 24 | 25 | 1. The fully qualified class name MUST have a top-level namespace name, 26 | also known as a "vendor namespace". 27 | 28 | 2. The fully qualified class name MAY have one or more sub-namespace 29 | names. 30 | 31 | 3. The fully qualified class name MUST have a terminating class name. 32 | 33 | 4. Underscores have no special meaning in any portion of the fully 34 | qualified class name. 35 | 36 | 5. Alphabetic characters in the fully qualified class name MAY be any 37 | combination of lower case and upper case. 38 | 39 | 6. All class names MUST be referenced in a case-sensitive fashion. 40 | 41 | 3. When loading a file that corresponds to a fully qualified class name ... 42 | 43 | 1. A contiguous series of one or more leading namespace and sub-namespace 44 | names, not including the leading namespace separator, in the fully 45 | qualified class name (a "namespace prefix") corresponds to at least one 46 | "base directory". 47 | 48 | 2. The contiguous sub-namespace names after the "namespace prefix" 49 | correspond to a subdirectory within a "base directory", in which the 50 | namespace separators represent directory separators. The subdirectory 51 | name MUST match the case of the sub-namespace names. 52 | 53 | 3. The terminating class name corresponds to a file name ending in `.php`. 54 | The file name MUST match the case of the terminating class name. 55 | 56 | 4. Autoloader implementations MUST NOT throw exceptions, MUST NOT raise errors 57 | of any level, and SHOULD NOT return a value. 58 | 59 | 60 | ## 3. Examples 61 | 62 | The table below shows the corresponding file path for a given fully qualified 63 | class name, namespace prefix, and base directory. 64 | 65 | | Fully Qualified Class Name | Namespace Prefix | Base Directory | Resulting File Path 66 | | ----------------------------- |--------------------|--------------------------|------------------------------------------- 67 | | \Acme\Log\Writer\File_Writer | Acme\Log\Writer | ./acme-log-writer/lib/ | ./acme-log-writer/lib/File_Writer.php 68 | | \Aura\Web\Response\Status | Aura\Web | /path/to/aura-web/src/ | /path/to/aura-web/src/Response/Status.php 69 | | \Symfony\Core\Request | Symfony\Core | ./vendor/Symfony/Core/ | ./vendor/Symfony/Core/Request.php 70 | | \Zend\Acl | Zend | /usr/includes/Zend/ | /usr/includes/Zend/Acl.php 71 | 72 | For example implementations of autoloaders conforming to the specification, 73 | please see the [examples file][]. Example implementations MUST NOT be regarded 74 | as part of the specification and MAY change at any time. 75 | 76 | [autoloading]: http://php.net/autoload 77 | [PSR-0]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md 78 | [examples file]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-4-autoloader-examples.md 79 | -------------------------------------------------------------------------------- /accepted/es/PSR-0.md: -------------------------------------------------------------------------------- 1 | Estándar de autocarga de clases 2 | =============================== 3 | 4 | > **Obsoleto** - A partir del 21/10/2014 el estándar PSR-0 se ha marcado como obsoleto. Ahora se recomienda [PSR-4] 5 | como alternativa. 6 | 7 | [PSR-4]: http://www.php-fig.org/psr/psr-4/ 8 | 9 | A continuación se describen los requisitos obligatorios que deben cumplirse para la interoperabilidad del autoloader. 10 | 11 | Obligatorio 12 | ----------- 13 | 14 | * Un espacio de nombres y clase completamente cualificada debe tener la siguiente estructura `\\(\)*`. 15 | * Cada espacio de nombres debe tener un espacio de nombres de nivel superior ("Nombre del proveedor"). 16 | * Cada espacio de nombres puede tener tantos sub-espacios de nombres como sea necesario. 17 | * Cada separador de espacio de nombres se convierte en la constante `DIRECTORY_SEPARATOR` cuando se carga desde el sistema de archivos. [^1] 18 | * Cada carácter `_` en el nombre de la clase se convierte en la constante `DIRECTORY_SEPARATOR`. El carácter `_` no tiene ningún significado especial en el espacio de nombres. 19 | * Al espacio de nombres y la clase completamente cualificada se le añade el sufijo `.php` cuando se cargue desde el sistema de archivos. 20 | * Los caracteres alfabéticos en los nombres de proveedor, espacios de nombres y nombres de clase pueden contener cualquier combinación de mayúsculas y minúsculas. 21 | 22 | Ejemplos 23 | ---------- 24 | 25 | * `\Doctrine\Common\IsolatedClassLoader` => `/directorio/del/proyecto/lib/vendor/Doctrine/Common/IsolatedClassLoader.php` 26 | * `\Symfony\Core\Request` => `/directorio/del/proyecto/lib/vendor/Symfony/Core/Request.php` 27 | * `\Zend\Acl` => `/directorio/del/proyecto/lib/vendor/Zend/Acl.php` 28 | * `\Zend\Mail\Message` => `/directorio/del/proyecto/lib/vendor/Zend/Mail/Message.php` 29 | 30 | Guiones bajos en Espacios de nombres y nombres de Clase 31 | -------------------------------------------------------- 32 | 33 | * `\espacio_de_nombres\paquete\Nombre_De_Clase` => `/directorio/del/proyecto/lib/proveedor/espacio_de_nombres/paquete/Nombre/De/Clase.php` 34 | * `\espacio_de_nombres\nombre_de_paquete\Nombre_De_Clase` => `/directorio/del/proyecto/lib/proveedor/espacio_de_nombres/nombre_de_paquete/Nombre/De/Clase.php` 35 | 36 | El estándar aquí descrito, debe ser el mínimo común denominador para la interoperabilidad del autoloader. Puede comprobar que sigue estas normas mediante la utilización del la implementación de ejemplo de autoloader SplClassLoader, capaz de cargar clases de PHP 5.3. 37 | 38 | Ejemplo de implementación 39 | ---------------------------- 40 | 41 | A continuación, se muestra una función de ejemplo para demostrar de forma sencilla cómo se cargan de automáticamente las clases con la propuesta anterior. 42 | 43 | ```php 44 | ` o las etiquetas cortas para imprimir salida de información ``; NO DEBE emplear otras variantes. 34 | 35 | ### 2.2. Codificación de caracteres 36 | 37 | El código PHP DEBE utilizar codificación UTF-8 sin BOM. 38 | 39 | ### 2.3. Efectos secundarios 40 | 41 | Un archivo DEBERÍA declarar estructuras (clases, funciones, constantes, etc,...) y no causar efectos secundarios, o DEBERÍA ejecutar partes de la lógica de negocio, pero NO DEBERÍA hacer las dos cosas. 42 | 43 | La frase "efectos secundarios" significa: que la ejecución de la lógica de negocio no está directamente relacionado con declarar clases, funciones, constantes, etc, *simplemente la de incluir el archivo*. 44 | 45 | "Efectos secundarios" incluyen, pero no se limitan a: generar salidas, uso explícito de `requiere` o `include`, conexiones a servicios externos, modificación de configuraciones iniciales, enviar errores o excepciones, modificar variables globales o estáticas, leer o escribir un archivo, etc. 46 | 47 | El siguiente ejemplo muestra un archivo que incluye las dos: declaraciones y efectos secundarios; Un ejemplo de lo que debe evitar: 48 | 49 | ```php 50 | \n"; 59 | 60 | // declaración 61 | function foo() 62 | { 63 | // cuerpo de la función 64 | } 65 | ``` 66 | 67 | El siguiente ejemplo es el de un archivo que contiene declaraciones sin efectos secundarios; Un ejemplo que puede seguir: 68 | 69 | ```php 70 | ** Obsolète ** - Le 21/10/2014 PSR-0 a été marqué comme obsolète. [PSR-4] est maintenant l'alternative recommandée. 5 | 6 | [PSR-4]: http://www.php-fig.org/psr/psr-4/fr/ 7 | 8 | La section suivante décrit les conditions obligatoires qui doivent être 9 | respectées pour l'interopérabilité avec un chargeur de classes. 10 | 11 | Obligatoire 12 | ----------- 13 | 14 | * Les classes et les espaces de noms entièrement qualifiés doivent disposer de 15 | la structure suivante 16 | `\\(\)*`. 17 | * Chaque espace de noms doit avoir un espace de noms racine. ("Nom du Vendor"). 18 | * Chaque espace de noms peut avoir autant de sous-espaces de noms qu'il le 19 | souhaite. 20 | * Chaque séparateur d'un espace de noms est converti en `DIRECTORY_SEPARATOR` 21 | lors du chargement à partir du système de fichiers. 22 | * Chaque "\_" dans le nom d'une CLASSE est converti en `DIRECTORY_SEPARATOR`. Le 23 | caractère "\_" n'a pas de signification particulière dans un espace de noms. 24 | * Les classes et espaces de noms complètement qualifiés sont suffixés avec 25 | ".php" lors du chargement à partir du système de fichiers. 26 | * Les caractères alphabétiques dans les noms de vendors, espaces de noms et noms 27 | de classes peuvent contenir n'importe quelle combinaison de minuscules et de 28 | majuscules. 29 | 30 | Exemples 31 | -------- 32 | 33 | * `\Doctrine\Common\IsolatedClassLoader` => `/chemin/vers/projet/lib/vendor/Doctrine/Common/IsolatedClassLoader.php` 34 | * `\Symfony\Core\Request` => `/chemin/vers/projet/lib/vendor/Symfony/Core/Request.php` 35 | * `\Zend\Acl` => `/chemin/vers/projet/lib/vendor/Zend/Acl.php` 36 | * `\Zend\Mail\Message` => `/chemin/vers/projet/lib/vendor/Zend/Mail/Message.php` 37 | 38 | Sous-tiret dans les Espaces de Noms et Noms de Classes 39 | ------------------------------------------------------ 40 | 41 | * `\espace de noms\package\Class_Name` => `/chemin/vers/projet/lib/vendor/espace de noms/package/Class/Name.php` 42 | * `\espace de noms\package_name\Class_Name` => `/chemin/vers/projet/lib/vendor/espace de noms/package_name/Class/Name.php` 43 | 44 | Les standards établis ici doivent avoir le plus petit dénominateur commun pour 45 | assurer une bonne interopérabilité des chargeurs de classes. Vous pouvez 46 | vérifier que vous respectez ces standards via l'utilisation de l'implémentation 47 | d'exemple de SplClassLoader qui est capable de charger les classes PHP 5.3. 48 | 49 | Exemple d'implémentation 50 | ------------------------ 51 | 52 | Le code ci-dessous est un exemple de fonction permettant de montrer comment les 53 | standards proposés ci-dessus peuvent être chargés automatiquement. 54 | 55 | ```php 56 | ou bien les tags courts 41 | . On NE DOIT PAS utiliser d'autres variantes. 42 | 43 | ### 2.2. Encodage des caractères 44 | 45 | Le code PHP DOIT utiliser uniquement UTF-8 sans BOM. 46 | 47 | ### 2.3. Les effets secondaires 48 | 49 | Un fichier DEVRAIT déclarer des nouveaux symboles (classes, fonctions, 50 | constantes, etc.) et ne pas causer d’effets secondaires, ou il DEVRAIT exécuter 51 | de la logique avec effets secondaires, mais NE DEVRAIT PAS faire les deux. 52 | 53 | La phrase "effets secondaires" signifie l’exécution de la logique qui n’est pas 54 | liée directement à la déclaration de classes, fonctions, constantes, etc., 55 | *simplement par l’inclusion du fichier.* 56 | 57 | Les "effets secondaires" comprennent, mais ne sont pas limités à : générer une 58 | sortie, utilisation explicite de `require` ou `include`, connexion à des 59 | services externes, modification de paramètres ini, émission d'erreurs ou 60 | d'exceptions, modification de variables globales ou statiques, lecture ou 61 | écriture dans un fichier et ainsi de suite. 62 | 63 | Le code suivant est un exemple d’un fichier avec déclarations et effets 64 | secondaires ; c’est-à-dire, un exemple de ce qu’il faut éviter : 65 | 66 | ```php 67 | \n"; 76 | 77 | // déclaration 78 | function foo() 79 | { 80 | // corps de la fonction 81 | } 82 | ``` 83 | 84 | L'exemple suivant est un fichier qui contient des déclarations sans 85 | effets secondaires, c’est-à-dire, un exemple à émuler : 86 | 87 | ```php 88 | (\)*\ 25 | 26 | 1. Le nom de classe entièrement qualifié DOIT avoir un namespace de haut 27 | niveau, aussi connu comme un "espace de noms du fournisseur". 28 | 29 | 2. Le nom de classe entièrement qualifié PEUT avoir un ou plusieurs noms de 30 | sous-namespace. 31 | 32 | 3. Le nom de classe entièrement qualifié DOIT finir par un nom de classe. 33 | 34 | 4. Les underscores n'ont aucune signification particulière dans quelque 35 | parti que ce soit du nom de classe entièrement qualifié. 36 | 37 | 5. Les caractères alphabétiques dans le nom de classe entièrement qualifié 38 | PEUVENT être n'importe quelle combinaison de minuscules et majuscules. 39 | 40 | 6. Tous les noms de classe DOIVENT être référencés en tenant compte de la 41 | casse. 42 | 43 | 3. Lors du chargement d'un fichier qui correspond à un nom de classe entièrement 44 | qualifié ... 45 | 46 | 1. Une série contiguë d'un ou plusieurs namespace et sous-namespace, 47 | n'incluant pas le séparateur de namespace principal, dans le nom de 48 | classe entièrement qualifié (un "préfixe de namespace") correspond à au 49 | moins un "répertoire de base". 50 | 51 | 2. Les noms contigus de sous-namespace après le "préfixe de namespace" 52 | correspondent à un sous-répertoire dans un "répertoire de base", dans 53 | lequel les séparateurs de namespace représentent des séparateurs de 54 | répertoires. Le nom de sous-répertoire DOIT correspondre à la casse des 55 | noms de sous-namespaces. 56 | 57 | 3. Le nom de la classe de fin correspond à un nom de fichier se terminant 58 | par `.php`. Le nom du fichier DOIT correspondre à la casse du nom de 59 | la classe de fin. 60 | 61 | 4. Les implémentations d'auto-chargement de classe NE DOIVENT PAS créer 62 | d'exceptions, NE DOIVENT PAS provoquer d'erreur de quelque niveau que ce 63 | soit, et de NE DEVRAIT PAS retourner de valeur. 64 | 65 | 66 | ## 3. Exemples 67 | 68 | Le tableau ci-dessous montre le chemin du fichier correspondant à un nom de 69 | classe entièrement qualifié, le préfixe du namespace, et le répertoire de base. 70 | 71 | 72 | 73 | | Nom de Classe Entièrement Qualifié | Préfixe du Namespace | Répertoire de Base | Chemin du Fichier Résultant 74 | | --------------------------------------|-----------------------|---------------------------|---------------------------- 75 | | \Acme\Log\Writer\File_Writer | Acme\Log\Writer | ./acme-log-writer/lib/ | ./acme-log-writer/lib/File_Writer.php 76 | | \Aura\Web\Response\Status | Aura\Web | /path/to/aura-web/src/ | /path/to/aura-web/src/Response/Status.php 77 | | \Symfony\Core\Request | Symfony\Core | ./vendor/Symfony/Core/ | ./vendor/Symfony/Core/Request.php 78 | | \Zend\Acl | Zend | /usr/includes/Zend/ | /usr/includes/Zend/Acl.php 79 | 80 | Pour des exemples d'implémentations d'auto-chargement conformes à la 81 | spécification, voir les [fichiers d'exemple][]. Les exemples d'implémentations 82 | NE DOIVENT PAS être considérées comme faisant partie de la spécification et 83 | PEUVENT changer à tout moment. 84 | 85 | 86 | [RFC 2119]: http://tools.ietf.org/html/rfc2119 87 | [auto-chargement]: http://php.net/autoload 88 | [PSR-0]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md 89 | [fichiers d'exemple]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-4-autoloader-examples.md 90 | -------------------------------------------------------------------------------- /accepted/it/PSR-0.md: -------------------------------------------------------------------------------- 1 | Quanto segue descrive i requisiti necessari ai quali ci si deve uniformare 2 | per garantire l'interoperabilità tra gli autoloader. 3 | 4 | Obblighi 5 | --------- 6 | 7 | * Il fully-qualified namespace e la classe devono avere la seguente 8 | struttura `\\(\)*` 9 | * Ogni namespace deve avere un namespace di primo livello ("Nome Vendor"). 10 | * Ogni namespace può avere una quantità arbitraria di sotto-namespace. 11 | * Ogni separatore di namespace deve essere convertito in un `DIRECTORY_SEPARATOR` al 12 | caricamento da file system. 13 | * Ogni carattere `_` nel NOME DELLA CLASSE deve essere convertito in un 14 | `DIRECTORY_SEPARATOR`. Il carattere `_` non ha nessun significato particolare nel 15 | namespace. 16 | * Al fully-qualified namespace e alla classe viene apposto il suffisso `.php` al 17 | caricamento da file system. 18 | * I caratteri alfabetici nei nomi dei vendor, nei namespace, e nei nomi delle classi possono 19 | formare una qualsiasi combinazione di caratteri minuscoli e caratteri maiuscoli. 20 | 21 | Esempi 22 | -------- 23 | 24 | * `\Doctrine\Common\IsolatedClassLoader` => `/percorso/del/mio/progetto/lib/vendor/Doctrine/Common/IsolatedClassLoader.php` 25 | * `\Symfony\Core\Request` => `/percorso/del/mio/progetto/lib/vendor/Symfony/Core/Request.php` 26 | * `\Zend\Acl` => `/percorso/del/mio/progetto/lib/vendor/Zend/Acl.php` 27 | * `\Zend\Mail\Message` => `/percorso/del/mio/progetto/lib/vendor/Zend/Mail/Message.php` 28 | 29 | Underscore nei Namespace e nei Nomi delle Classi 30 | ------------------------------------------------- 31 | 32 | * `\namespace\package\Nome_Classe` => `/percorso/del/mio/progetto/lib/vendor/namespace/package/Nome/Classe.php` 33 | * `\namespace\package_name\Nome_Classe` => `/percorso/del/mio/progetto/lib/vendor/namespace/package_name/Nome/Classe.php` 34 | 35 | Gli standard che abbiamo fissato dovrebbero essere il minimo comune 36 | denominatore per l'interoperabilità indolore tra gli autoloader. Puoi 37 | verificare l'aderenza del tuo codice agli standard utilizzando questa 38 | implementazione esemplificativa dell'SplClassLoader, in grado di caricare 39 | classi PHP 5.3. 40 | 41 | Esempio di implementazione 42 | --------------------------- 43 | 44 | Di seguito una funzione per dimostrare im modo semplice come gli standard 45 | proposti in precedenza permettano il caricamento automatico delle classi. 46 | 47 | ```php 48 | ` o la versione 44 | dei tag short-echo ``; NON DEVONO essere usate altre varianti dei tag. 45 | 46 | ### 2.2. Codifica dei caratteri 47 | 48 | Per il codice PHP si DEVE usare soltanto UTF-8 senza BOM. 49 | 50 | ### 2.3. Effetti collaterali 51 | 52 | Un file DOVREBBE dichiarare nuovi simboli (classi, funzioni, costanti, 53 | etc.) senza causare altri effetti collaterali, oppure DOVREBBE eseguire logica 54 | con effetti collaterali, ma NON DOVREBBE fare entrambe le cose. 55 | 56 | Con l'espressione "effetti collaterali" si intende l'esecuzione di logica non 57 | direttamente correlata alla dichiarazione delle classi, delle funzioni, delle 58 | costanti, etc., *al di fuori dell'inclusione del file*. 59 | 60 | Gli "effetti collaterali" includono, ma non sono limitati ai seguenti casi: 61 | generazione di output, uso esplicito di `require` o `include`, connessione a 62 | servizi esterni, modifica delle impostazioni ini, emissione di errori o eccezioni, 63 | modifica di variabili globali o statiche, lettura o scrittura di file, e così via. 64 | 65 | Di seguito un esempio con un file in cui sono presenti sia dichiarazioni che effetti 66 | collaterali; ecco un esempio di quello che va evitato: 67 | 68 | ```php 69 | \n"; 78 | 79 | // dichiarazione 80 | function foo() 81 | { 82 | // corpo della funzione 83 | } 84 | ``` 85 | 86 | L'esempio che segue è un file che contiene dichiarazioni senza effetti 87 | collaterali; ecco un esempio da imitare: 88 | 89 | ```php 90 | (\)*\ 24 | 25 | 1. Il nome di classe completamente qualificato DEVE aver un nome di 26 | namespace di primo livello, detto anche "namespace del vendor". 27 | 28 | 2. Il nome di classe completamente qualificato PUÒ avere uno o più 29 | nomi di sotto-namespace. 30 | 31 | 3. Il nome di classe completamente qualificato DEVE terminare con il 32 | nome della classe. 33 | 34 | 4. Gli underscore non hanno nessun significato speciale in alcuna parte 35 | del nome di classe completamente qualificato. 36 | 37 | 5. I caratteri alfabetici all'interno del nome di classe completamente 38 | qualificato POSSONO essere una qualunque combinazione di caratteri 39 | maiuscoli o minuscoli. 40 | 41 | 6. Tutti i nomi di classe DEVONO essere riportati tenendo conto delle 42 | maiuscole o minuscole. 43 | 44 | 3. Quando si carica un file che corrisponde ad un nome di classe completamente 45 | qualificato... 46 | 47 | 1. Una serie contigua di uno o più nomi di namespace e sotto-namespace 48 | posti all'inizio, escludendo il separatore di namespace posto in testa, 49 | prensenti nel nome di classe completamente qualificato (un "prefisso di 50 | namespace"), corrisponde ad almeno una "cartella di base". 51 | 52 | 2. I nomi di sotto-namespace contigui che seguono il "prefisso di namespace" 53 | corrispondono ad una sotto-cartella all'interno della "cartella di base", 54 | in cui i separatori di namespace rappresentano i separatori di cartella. 55 | I nomi delle sotto-cartelle DEVONO corrispondere ai nomi dei sotto-namespace 56 | in termini di maiuscole e minuscole. 57 | 58 | 3. Il nome di classe finale deve corrispondere ad un nome di file che 59 | termina con `.php`. Il nome del file DEVE corrispondere al nome della 60 | classe in termini di maiuscole e minuscole. 61 | 62 | 4. Le implementazioni dell'autoloader NON DEVONO lanciare eccezioni, NON DEVONO 63 | causare errori di qualunque livello, e NON DOVREBBERO ritornare alcun valore. 64 | 65 | ## 3. Esempi 66 | 67 | La tabella sottostante mostra il percorso completo corrispondente ad un dato 68 | nome di classe completamente qualificato, prefisso di namespace e cartella di base. 69 | 70 | | Nome completamente qualif. | Pref. di Namespace | Cartella di base | Percorso completo corrispondente 71 | | ----------------------------- |--------------------|--------------------------|------------------------------------------- 72 | | \Acme\Log\Writer\File_Writer | Acme\Log\Writer | ./acme-log-writer/lib/ | ./acme-log-writer/lib/File_Writer.php 73 | | \Aura\Web\Response\Status | Aura\Web | /path/to/aura-web/src/ | /path/to/aura-web/src/Response/Status.php 74 | | \Symfony\Core\Request | Symfony\Core | ./vendor/Symfony/Core/ | ./vendor/Symfony/Core/Request.php 75 | | \Zend\Acl | Zend | /usr/includes/Zend/ | /usr/includes/Zend/Acl.php 76 | 77 | Per implementazioni di esempio di autoloader conformi alle specifiche, vedere il 78 | [file di esempio][]. Le implementazioni di esempio NON DEVONO essere considerate 79 | come parte delle specifiche e POTREBBERO cambiare in ogni momento. 80 | 81 | [autoloading]: http://php.net/autoload 82 | [PSR-0]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md 83 | [file di esempio]: https://github.com/php-fig/fig-standards/blob/master/accepted/it/PSR-4-autoloader-examples.md 84 | -------------------------------------------------------------------------------- /accepted/pl/PSR-0.md: -------------------------------------------------------------------------------- 1 | Standardy autoloadingu 2 | ================================== 3 | 4 | > **Porzucony** - W dniu 2014-10-21 standard PSR-0 został porzucony na rzecz [PSR-4]. 5 | 6 | [PSR-4]: http://www.php-fig.org/psr/psr-4/ 7 | 8 | Poniższy dokument opisuje obowiązkowe wymagania, do których należy się zastosować 9 | w celu ustandaryzowania procesu autoloadingu klas. 10 | 11 | Wymagania 12 | --------- 13 | 14 | * W pełni poprawna przestrzeń nazw (namespace) i nazwa klasy muszą posiadać następującą strukturę 15 | `\\(\)*` 16 | * Każda przestrzeń nazw musi posiadać przestrzeń bazową ("Nazwa Vendora"). 17 | * Każda przestrzeń nazw może posiadać dowolną ilość podprzestrzeni. 18 | * Każdy separator między przestrzeniami nazw jest zamieniany na stałą `DIRECTORY_SEPARATOR` 19 | podczas ładowania z systemu plików. 20 | * Każdy znak `_` w nazwie klasy jest konwertowany do wartości stałej `DIRECTORY_SEPARATOR`. 21 | Znak `_` nie ma żadnego specjalnego znaczenia w przestrzeni nazw. 22 | * W pełni poprawny plik przestrzeni nazw i klasy musi kończyć się rozszerzeniem `.php` podczas ładowania z systemu plików. 23 | * Wielkość znaków (duże/małe litery) w przestrzeni bazowej ("Nazwa Vendora"), przestrzeniach nazw czy klasach nie ma żadnego znaczenia. 24 | 25 | Przykłady 26 | --------- 27 | 28 | * `\Doctrine\Common\IsolatedClassLoader` => `/path/to/project/lib/vendor/Doctrine/Common/IsolatedClassLoader.php` 29 | * `\Symfony\Core\Request` => `/path/to/project/lib/vendor/Symfony/Core/Request.php` 30 | * `\Zend\Acl` => `/path/to/project/lib/vendor/Zend/Acl.php` 31 | * `\Zend\Mail\Message` => `/path/to/project/lib/vendor/Zend/Mail/Message.php` 32 | 33 | Znaki podkreślenia w przestrzeniach nazw i nazwach klas 34 | ------------------------------------------------------- 35 | 36 | * `\namespace\package\Class_Name` => `/path/to/project/lib/vendor/namespace/package/Class/Name.php` 37 | * `\namespace\package_name\Class_Name` => `/path/to/project/lib/vendor/namespace/package_name/Class/Name.php` 38 | 39 | Opisane powyżej reguły powinny być najbardziej uniwersalnym rozwiązaniem problemu autoloadingu klas w PHP. 40 | W każdym momencie można wypróbować działanie powyższych standardów poprzez implementację klasy SplClassLoader – 41 | będzie ona działać poprawnie już dla projektów opartych o wersję PHP 5.3. 42 | 43 | Przykładowa implementacja 44 | ------------------------- 45 | 46 | Poniższy przykład demonstruje jak powinna wyglądać implementacja autloadingu na podstawie powyższych standardów. 47 | 48 | ```php 49 | ` lub z krótkich ``, 42 | NIE WOLNO korzystać z innych tagów otwierających/zamykających. 43 | 44 | ### 2.2. Kodowanie znaków 45 | 46 | Kod php MUSI być zapisywany w kodowaniu UTF-8 bez BOM. 47 | 48 | ### 2.3. Skutki uboczne 49 | 50 | W programowaniu termin "skutek/efekt uboczny" oznacza efekt wyrażenia, albo wywołania funkcji lub metody, 51 | który wykracza poza zwrócenie wartości. Przykładem "skutków ubocznych" może być interakcja z systemem operacyjnym, lub zmiana wartości zmiennej globalnej. 52 | 53 | Pojedynczy plik POWINIEN zawierać deklaracje struktur języka php (klas, funkcji, stałych itp.) LUB definować 54 | zachowanie czyli tak zwane "skutki uboczne" (np. generowanie wyjścia, zmiana parametrów konfiguracyjnych .ini itp.). 55 | 56 | Plik NIE POWINIEN wykonywać tych dwóch rzeczy na raz. Efekty uboczne w php to m.in. generowanie wyjścia (np. `echo`, `var_dump`), 57 | używanie `require` lub `include`, podłączenie do zewnętrznej usługi, modyfikacja parametrów ini, 58 | rzucanie błędów lub wyjątków, modyfikacja globalnych lub statycznych zmiennych, czytanie lub zapis z/do pliku itd. 59 | 60 | Poniższy przykład posiada zarówno deklaracje funkcji jak i ma skutki uboczne. Przykład pokazuje czego należy unikać: 61 | 62 | ```php 63 | \n"; 72 | 73 | // deklaracja 74 | function foo() 75 | { 76 | // ciało funkcji 77 | } 78 | ``` 79 | 80 | Kolejny przykład zawiera w sobie tylko deklaracje (tutaj funkcji). Przykład pokazuje jak powinniśmy pisać: 81 | 82 | ```php 83 | (\)*\ 25 | 26 | 1. W pełni poprawna nazwa klasy MUSI posiadać bazową przestrzeń nazw, 27 | zwaną także "przestrzenią vendora". 28 | 29 | 2. W pełni poprawna nazwa klasy MOŻE posiadać jedną lub wiele podprzestrzeni nazw. 30 | 31 | 3. W pełni poprawna nazwa klasy MUSI posiadać nazwę klasy na końcu. 32 | 33 | 4. Znak podkreślenia nie ma żadnego specjalnego znaczenia w pełni 34 | poprawnej nazwie klasy. 35 | 36 | 5. W pełni poprawna nazwa klasy MOŻE posiadać dowolny porządek znaków 37 | alfabetu różnej wielkości (małe/duże litery). 38 | 39 | 6. Wszystkie nazwy klas MUSZĄ być wywoływane z uwzględnieniem małych i wielkich liter. 40 | 41 | 3. Kiedy wczytujemy plik, który odpowiada w pełni poprawnej nazwie klasy... 42 | 43 | 1. Sąsiadujące ze sobą nazwy przestrzeni bazowej oraz podprzestrzeni 44 | (bez uwzględnienia początkowego separatora przestrzeni bazowej) w pełni poprawnej 45 | nazwie klasy zwane są "prefiksem przestrzeni nazw" i odpowiadają przynajmniej jednemu 46 | "katalogowi bazowemu". 47 | 48 | 2. Sąsiadujące ze sobą nazwy podprzestrzeni występujące po "prefiksie przestrzeni nazw" 49 | odpowiadają podkatalogowi w "katalogu bazowym", gdzie separatory przestrzeni nazw reprezentują 50 | separatory katalogów. Nazwa (ścieżka) podkatalogu MUSI być zgodna z nazwami podprzestrzeni. 51 | 52 | 3. Końcowa nazwa klasy odpowiada plikowi kończącemu się na `.php`. 53 | Nazwa pliku MUSI być zgodna z ostatnim segmentem w pełni poprawnej nazwy klasy. 54 | 55 | 4. Implementacji autoloadera NIE WOLNO rzucać wyjątków, NIE WOLNO zgłaszać 56 | jakichkolwiek błędów, implementacja NIE POWINNA także zwracać wartości. 57 | 58 | 59 | ## 3. Przykłady 60 | 61 | Poniższa tabela przedstawia w pełni poprawne nazwy klas, prefiksy przestrzeni 62 | nazw oraz bazowy katalog, które wskazują na ścieżkę do pliku. 63 | 64 | | W pełni poprawna nazwa klasy | Prefiks przestrzeni nazw | Bazowy katalog | Wynikowa ścieżka pliku 65 | | ----------------------------- |--------------------------|--------------------------|------------------------------------------ 66 | | \Acme\Log\Writer\File_Writer | Acme\Log\Writer | ./acme-log-writer/lib/ | ./acme-log-writer/lib/File_Writer.php 67 | | \Aura\Web\Response\Status | Aura\Web | /path/to/aura-web/src/ | /path/to/aura-web/src/Response/Status.php 68 | | \Symfony\Core\Request | Symfony\Core | ./vendor/Symfony/Core/ | ./vendor/Symfony/Core/Request.php 69 | | \Zend\Acl | Zend | /usr/includes/Zend/ | /usr/includes/Zend/Acl.php 70 | 71 | Aby przejrzeć przykładową implementację autloadera zgodnego ze specyfikacja, 72 | można przejść do [pliku przykładu][]. NIE WOLNO uważać przykładowej implementacji 73 | za część specyfikacji, MOŻE się ona zmienić w każdej chwili. 74 | 75 | [automatycznego ładowania]: http://php.net/autoload 76 | [PSR-0]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md 77 | [pliku przykładu]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-4-autoloader-examples.md 78 | -------------------------------------------------------------------------------- /accepted/pt-BR/PSR-0.md: -------------------------------------------------------------------------------- 1 | Padrão de Autoload 2 | ================== 3 | 4 | A seguir são descritos os requisitos obrigatórios que devem ser aderidos para permitir a interoperabilidade do autoloader. 5 | 6 | Obrigatório 7 | ----------- 8 | 9 | * Os nomes completos de um namespace e sua classe devem ter a seguinte estrutura `\\(\)*` 10 | * Cada namespace deve ter um namespace no nivel raíz ("Vendor Name"). 11 | * Cada namespace pode ter quantos sub-namespaces forem necessários. 12 | * Cada separador de namespace é convertido para um `DIRECTORY_SEPARATOR` quando carregando do sistema de arquivos. 13 | * Cada caractér `_` no CLASS NAME é convertido para um `DIRECTORY_SEPARATOR`. O Caractér `_` não tem nenhum significado especial no namespace. 14 | * Os nomes completos de um namespace e sua classe recebem o sufixo `.php` quando carregando do sistema de arquivos. 15 | * Caracteres nos nomes do vendor, dos namespaces e das classes podem ser qualquer combinação de maiúsculas e minúsculas. 16 | 17 | Exemplos 18 | -------- 19 | 20 | * `\Doctrine\Common\IsolatedClassLoader` => `/path/to/project/lib/vendor/Doctrine/Common/IsolatedClassLoader.php` 21 | * `\Symfony\Core\Request` => `/path/to/project/lib/vendor/Symfony/Core/Request.php` 22 | * `\Zend\Acl` => `/path/to/project/lib/vendor/Zend/Acl.php` 23 | * `\Zend\Mail\Message` => `/path/to/project/lib/vendor/Zend/Mail/Message.php` 24 | 25 | Underscores em nomes de Namespaces e Classes 26 | -------------------------------------------- 27 | 28 | * `\namespace\package\Class_Name` => `/path/to/project/lib/vendor/namespace/package/Class/Name.php` 29 | * `\namespace\package_name\Class_Name` => `/path/to/project/lib/vendor/namespace/package_name/Class/Name.php` 30 | 31 | As padronizações que definimos aqui deveriam ser o mais baixo denominador comum para a interoperabilidade indolor do autoloader. Você pode testar se você está seguindo estes padrões utilizando esse exemplo de implementação de SplClassLoader que é capáz de carregar classes do PHP 5.3. 32 | 33 | Implementação de Exemplo 34 | ------------------------ 35 | 36 | Abaixo está um exemplo de função para simplesmente demonstrar como os padrões propostos acima funcionam para o carregamento automático. 37 | 38 | ```php 39 | ` ou as tags de short-echo ``; NÃO DEVEM utilizar mais nenhuma variação de tags. 37 | 38 | ### 2.2. Codificação de Caracteres 39 | 40 | Códigos PHP DEVEM utilizar somente UTF-8 sem BOM. 41 | 42 | ### 2.3. Efeitos Colaterais 43 | 44 | Um arquivo DEVERIA declarar novos simbolos (classes, funções, constantes, etc.) e causar mais nenhum efeito colateral, ou DEVERIA executar lógica com efeitos colaterais, mas NÃO DEVERIA fazer ambos. 45 | 46 | O termo "efeitos colaterais" significa execução de lógica não diretamente relacionada à declarar classes, funções, constantes, etc., *meramente por incluir o arquivo*. 47 | 48 | "Efeitos colaterais" incluem, mas não são limitadas à: gerar output, utilização explícita de `require` ou `include`, conectar à serviços externos, modificar configurações no php.ini, emissão de erros ou exceções, modificar variáveis globais ou estáticas, lendo de ou escrevendo em um arquivo, etc. 49 | 50 | A seguir um exemplo de um arquivo com declarações e efeitos colaterais; ou seja um exemplo do que evitar: 51 | 52 | ```php 53 | \n"; 62 | 63 | // declaração 64 | function foo() 65 | { 66 | // corpo da função 67 | } 68 | ``` 69 | 70 | A seguir um exemplo de um arquivo que contém somente declarações; ou seja, um exemplo do que seguir: 71 | 72 | ```php 73 | get('/hello/{name}', function ($name) use ($app) { 32 | return 'Hello '.$app->escape($name); 33 | }); 34 | ``` 35 | 36 | 2. _[10/17/2013]_ Quando extendendo múltiplas interfaces, a lista de `extends` deveria ser tratada do mesmo jeito que uma lista de`implements`, como declarado na seção 4.1. 37 | 38 | -------------------------------------------------------------------------------- /accepted/ru/PSR-0.md: -------------------------------------------------------------------------------- 1 | Стандарт Автозагрузки 2 | ===================== 3 | 4 | > **Deprecated** - По состоянию на 21 октября 2014 года PSR-0 был помечен как устаревший. 5 | В настоящее время рекомендуется использовать [PSR-4] в качестве замены. 6 | 7 | [PSR-4]: http://www.php-fig.org/psr/psr-4/ 8 | 9 | Ниже описаны обязательные требования, которые должны быть выполнены для совместимости с автозагрузчиком классов. 10 | 11 | Обязательно 12 | ----------- 13 | 14 | * Полное пространство имён вместе с классом должны иметь следующую структуру `\<Имя производителя>\(<Пространство имён>\)*<Имя класса>` 15 | * У каждого пространства имён должен быть корневой уровень («Имя Производителя»). 16 | * У каждого пространства имён при необходимости может быть неограниченное количество подуровней. 17 | * Все разделители пространства имён преобразуются в `DIRECTORY_SEPARATOR` при загрузке из файловой системы. 18 | * Каждый символ `_` в ИМЕНИ КЛАССА преобразуется в `DIRECTORY_SEPARATOR`. Символ `_` не имеет специального значения в пространстве имён. 19 | * Полное пространство имён вместе с классом дополняются суффиксом `.php` при загрузке из файловой системы. 20 | * Названия производителей, пространства имен и имена классов могут содержать любую комбинацию строчных и заглавных букв. 21 | 22 | Примеры 23 | ------- 24 | 25 | * `\Doctrine\Common\IsolatedClassLoader` => `/path/to/project/lib/vendor/Doctrine/Common/IsolatedClassLoader.php` 26 | * `\Symfony\Core\Request` => `/path/to/project/lib/vendor/Symfony/Core/Request.php` 27 | * `\Zend\Acl` => `/path/to/project/lib/vendor/Zend/Acl.php` 28 | * `\Zend\Mail\Message` => `/path/to/project/lib/vendor/Zend/Mail/Message.php` 29 | 30 | Подчеркивания в пространстве имён и именах классов 31 | -------------------------------------------------- 32 | 33 | * `\namespace\package\Class_Name` => `/path/to/project/lib/vendor/namespace/package/Class/Name.php` 34 | * `\namespace\package_name\Class_Name` => `/path/to/project/lib/vendor/namespace/package_name/Class/Name.php` 35 | 36 | Указанные выше стандарты являются минимальным требованием для совместимости с автозагрузчиками. Вы можете убедиться, что следуете стандартам, используя пример реализации SplClassLoader, который способен загружать классы PHP 5.3. 37 | 38 | Пример реализации 39 | ----------------- 40 | 41 | Ниже приведён пример функции, показывающей, как стандарты, предлагаемые выше, могут использоваться автозагрузчиком. 42 | 43 | ```php 44 | ` или сокращённую форму ``. 47 | Использование других вариантов тегов НЕДОПУСТИМО. 48 | 49 | ### 2.2. Кодировка символов 50 | 51 | Для кода PHP НЕОБХОДИМО использовать только UTF-8 без BOM. 52 | 53 | ### 2.3. Побочные действия 54 | 55 | В файле СЛЕДУЕТ объявлять новые символы (классы, функции, константы и 56 | т. д.), не выполняя побочных действий, либо СЛЕДУЕТ выполнять логику, но 57 | НЕ СЛЕДУЕТ делать и то и другое сразу. 58 | 59 | Выражение «побочные действия» означает выполнение *при подключении файла* 60 | действий, не связанных напрямую с объявлением классов, функций, констант и т. д. 61 | 62 | «Побочные действия» включают в себя (но не ограничиваются) генерацию вывода, 63 | явное использование `require` или `include`, подключение к внешним службам, 64 | изменение значений ini, вбрасывание ошибок или исключений, изменение глобальных 65 | или статических переменных, чтение или запись файлов и так далее. 66 | 67 | Ниже приведён пример файла, содержащего и объявления, и побочные действия, т. е. 68 | пример того, как делать не надо: 69 | 70 | 71 | ```php 72 | \n"; 81 | 82 | // объявление 83 | function foo() 84 | { 85 | // тело функции 86 | } 87 | ``` 88 | 89 | Следующий код содержит объявления без побочных действий, т. е. показывает 90 | пример того, как следует делать: 91 | 92 | ```php 93 | get('/hello/{name}', function ($name) use ($app) { 41 | return 'Hello '.$app->escape($name); 42 | }); 43 | ``` 44 | 45 | ### 3.2 - Расширение нескольких интерфейсов (17.10.2013) 46 | 47 | При расширении нескольких интерфейсов со списком `extends` следует поступать так же, как с `implements`, как описано в разделе 4.1. 48 | 49 | -------------------------------------------------------------------------------- /accepted/ru/PSR-4-autoloader.md: -------------------------------------------------------------------------------- 1 | # Автозагрузчик 2 | 3 | Ключевые слова «ДОЛЖНО» («MUST»), «НЕДОПУСТИМО» («MUST NOT»), «ТРЕБУЕТСЯ» 4 | («REQUIRED»), «НУЖНО» («SHALL»), «НЕ ПОЗВОЛЯЕТСЯ» («SHALL NOT»), «СЛЕДУЕТ» 5 | («SHOULD»), «НЕ СЛЕДУЕТ» («SHOULD NOT»), «РЕКОМЕНДУЕТСЯ» («RECOMMENDED»), 6 | «МОЖЕТ» («MAY») и «НЕОБЯЗАТЕЛЬНО» («OPTIONAL») 7 | в этом документе должны расцениваться так, как описано в [RFC 2119](http://tools.ietf.org/html/rfc2119). 8 | 9 | ## 1. Обзор 10 | 11 | Данный PSR описывает спецификацию для [автозагрузки][] классов на основе путей файлов. Она полностью взаимозаменяема и 12 | может использоваться в дополнение к любой другой спецификации автозагрузчика, включая [PSR-0][]. Данный PSR также 13 | описывает, где размещать файлы, которые будут загружаться в соответствии со спецификацией. 14 | 15 | 16 | ## 2. Спецификация 17 | 18 | 1. Термин «класс» обозначает как классы, так и интерфейсы, трейты и другие подобные структуры. 19 | 20 | 2. Абсолютное имя класса имеет следующую форму: 21 | 22 | \<ИмяПространстваИмён>(\<ИменаПодпространствИмён>)*\<ИмяКласса> 23 | 24 | 1. Абсолютное имя класса ДОЛЖНО включать в себя верхний уровень пространства имён, также известный как 25 | «имя производителя». 26 | 27 | 2. Абсолютное имя класса МОЖЕТ включать одно и более подпространство имён. 28 | 29 | 3. Абсолютное имя класса ДОЛЖНО заканчиваться именем класса. 30 | 31 | 4. Символы подчёркивания не имеют какого-либо особого значения в любой части абсолютного имени класса. 32 | 33 | 5. Для буквенных символов абсолютного пространства имён МОЖЕТ использоваться любая комбинация верхнего и нижнего 34 | регистра. 35 | 36 | 6. Все имена классов ДОЛЖНЫ использоваться в регистрозависимом стиле. 37 | 38 | 3. При загрузке файла, соответствующего абсолютному имени класса: 39 | 40 | 1. В абсолютном имени класса последовательность из одного или более ведущего пространства имён и подпространств 41 | имён («префикс пространства имён»), исключая ведущий разделитель, соответствует как минимум одной 42 | «базовой директории». 43 | 44 | 2. Последовательность подпространств имён, следующая за «префиксом пространства имён», соответствует поддиректории 45 | в «базовой директории». Разделители пространства имён соответствуют разделителям директорий. Имя поддиректории 46 | ДОЛЖНО иметь тот же регистр символов, что и имена подпространств имён. 47 | 48 | 3. Завершающее имя класса соответствует имени файла, заканчивающемуся на `.php`. Имя файла ДОЛЖНО совпадать иметь тот же 49 | регистр символов, что и завершающее имя класса. 50 | 51 | 4. В реализациях автозагрузчика НЕДОПУСТИМО выбрасывать исключения, НЕДОПУСТИМО вызывать ошибки любого уровня и 52 | НЕ СЛЕДУЕТ возвращать значение. 53 | 54 | 55 | ## 3. Примеры 56 | 57 | В таблице ниже показано соответствие пути к файлу, абсолютного имени класса, префикса пространства имён и базовой 58 | директории. 59 | 60 | | Абсолютное имя класса | Префикс пространства имён | Базовая директория | Путь к файлу 61 | | ----------------------------- |---------------------------|--------------------------|------------------------------------------- 62 | | \Acme\Log\Writer\File_Writer | Acme\Log\Writer | ./acme-log-writer/lib/ | ./acme-log-writer/lib/File_Writer.php 63 | | \Aura\Web\Response\Status | Aura\Web | /path/to/aura-web/src/ | /path/to/aura-web/src/Response/Status.php 64 | | \Symfony\Core\Request | Symfony\Core | ./vendor/Symfony/Core/ | ./vendor/Symfony/Core/Request.php 65 | | \Zend\Acl | Zend | /usr/includes/Zend/ | /usr/includes/Zend/Acl.php 66 | 67 | Примеры реализации автозагрузчиков, соответствующих спецификации, приведены в [файле примеров][]. НЕДОПУСТИМО рассматривать 68 | их как часть спецификации. Примеры МОГУТ измениться в любое время. 69 | 70 | [автозагрузки]: http://php.net/autoload 71 | [PSR-0]: https://github.com/php-fig/fig-standards/blob/master/accepted/ru/PSR-0.md 72 | [файле примеров]: https://github.com/php-fig/fig-standards/blob/master/accepted/ru/PSR-4-autoloader-examples.md 73 | -------------------------------------------------------------------------------- /accepted/sl/PSR-0.md: -------------------------------------------------------------------------------- 1 | Standard avtomatskega nalagalnika 2 | ================================= 3 | 4 | > **Opuščen** - Od 2014-10-21 je bil PSR-0 označen za opuščenega. [PSR-4] je sedaj priporočen 5 | kot alternativa. 6 | 7 | [PSR-4]: http://www.php-fig.org/psr/psr-4/ 8 | 9 | Sledeče opisuje obvezne zahteve, ki se jih morate držati 10 | za interoperabilnost avtomatskega nalagalnika. 11 | 12 | Obveznosti 13 | ---------- 14 | 15 | * Polno kvalificirani imenski prostor in razred morata imeti sledečo 16 | strukturo `\\(\)*` 17 | * Vsak imenski prostor mora imeti imenski prostor najvišje ravni ("t.i. Vendor Name oz. ime izdelovalca"). 18 | * Vsak imenski prostor ima lahko kolikor želite pod-imenskih prostorov. 19 | * Vsak ločevalec imenskega prostora je pretvorjen v t.i. `DIRECTORY_SEPARATOR`, ko 20 | nalaga iz datotečnega sistema. 21 | * Vsak znak `_` v imenu razreda je pretvorjen v 22 | `DIRECTORY_SEPARATOR`. Znak `_` nima kakšnega posebnega pomena v 23 | imenskem prostoru. 24 | * Polno kvalificirani imenski prostor in razred ima pripono `.php` ko 25 | se nalaga iz datotečnega sistema. 26 | * Znaki abecede v imenih izdelovalcev, imenskih prostorih in imenih razredov so lahko 27 | katerakoli kombinacija malih in velikih črk. 28 | 29 | Primeri 30 | ------- 31 | 32 | * `\Doctrine\Common\IsolatedClassLoader` => `/path/to/project/lib/vendor/Doctrine/Common/IsolatedClassLoader.php` 33 | * `\Symfony\Core\Request` => `/path/to/project/lib/vendor/Symfony/Core/Request.php` 34 | * `\Zend\Acl` => `/path/to/project/lib/vendor/Zend/Acl.php` 35 | * `\Zend\Mail\Message` => `/path/to/project/lib/vendor/Zend/Mail/Message.php` 36 | 37 | Podčrtaji v imenskih prostorih in imena razredov 38 | ------------------------------------------------ 39 | 40 | * `\namespace\package\Class_Name` => `/path/to/project/lib/vendor/namespace/package/Class/Name.php` 41 | * `\namespace\package_name\Class_Name` => `/path/to/project/lib/vendor/namespace/package_name/Class/Name.php` 42 | 43 | Standarde, ki jih tu nastavimo, bi morali biti najnižji skupni imenovalec za 44 | nebolečo interoperabilnost avtomatskega nalagalnika. Preverite lahko, da 45 | sledite tem standardom z uporabo tega primera SplClassLoader 46 | izvedbe, ki je zmožen naložiti PHP 5.3 razrede. 47 | 48 | Primer izvedbe 49 | -------------- 50 | 51 | Spodaj je primer funkcije, ki enostavno ponazarja, kako so zgoraj 52 | predlagani standardi avtomatsko naloženi. 53 | 54 | ```php 55 | ` značke ali kratke izpisne `` značke; NE SME uporabljati drugih različic značk. 43 | 44 | ### 2.2. Kodiranje znakov 45 | 46 | PHP koda MORA uporabljati samo UTF-8 brez BOM. 47 | 48 | ### 2.3. Stranski učinki 49 | 50 | Datoteka MORA deklarirati nove simbole (razrede, funkcije, konstante 51 | itd.) in ne povročati drugih stranskih učinkov, ali MORA izvrševati logiko s stranskimi 52 | učinki, vendar NE BI SMELA delati obojega. 53 | 54 | Fraza "stranski učinki" pomeni izvrševanje logike, ki ni direktno povezana z 55 | deklaracijo razredov, funkcij, konstant itd., *le iz vključevanja 56 | datoteke*. 57 | 58 | "Stranski učinki" vključujejo, vendar niso omejeni na: generiranje izpisa, eksplicitno 59 | uporabo `require` ali `include`, povezavo z zunanjimi storitvami, spreminjanje ini 60 | nastavitev, oddajo napak ali izjem, spreminjanje globalnih ali statičnih spremenljivk, 61 | branje iz ali pisanje v datoteko in tako naprej. 62 | 63 | Sledeči primer je datoteka, ki vljučuje tako deklaracijo in stranske učinke; 64 | t.j. primer, ki se ga je potrebno izogibati: 65 | 66 | ```php 67 | \n"; 76 | 77 | // declaration 78 | function foo() 79 | { 80 | // function body 81 | } 82 | ``` 83 | 84 | Sledeči primer je datoteka, ki vključuje deklaracijo brez stranskih 85 | učinkov; t.j. primer, ki ga je dobro posnemati: 86 | 87 | ```php 88 | get('/hello/{name}', function ($name) use ($app) { 39 | return 'Hello '.$app->escape($name); 40 | }); 41 | ``` 42 | 43 | ### 3.2 - Razširitev večih vmesnikov (10/17/2013) 44 | 45 | Ko razširjate več vmesnikov, bi moral seznam `razširitev` bi obravnavan enako kot seznam 46 | `implementacij`, kot je deklarirano v Sekciji 4.1. 47 | 48 | -------------------------------------------------------------------------------- /accepted/sl/PSR-3-logger-interface.md: -------------------------------------------------------------------------------- 1 | Vmesnik dnevnika - Logger Interface 2 | =================================== 3 | 4 | Ta dokument opisuje skupne vmesnike za knjižnice dnevnika. 5 | 6 | Glavni cilj je omogočati knjižnicam, da dobijo `Psr\Log\LoggerInterface` 7 | objekt in pišejo vanj dnevnike na enostaven in univerzalen način. Ogrodja 8 | in CMS-i, ki imajo zahteve po meri LAHKO razširjajo vmesnik za njihove lastne 9 | namene, vendar BI MORALI ostati kompatibilni s tem dokumentom. To zagotavlja, 10 | da uporabe tretje-osebnih knjižnic aplikacije lahko pišejo v 11 | centralen dnevnik aplikacije. 12 | 13 | Ključne besede "MORA", "NE SME", "ZAHTEVA", "PRIPOROČA", "LAHKO" in "NEOBVEZNO" 14 | v tem dokumentu se tolmačijo, kot je navedeno v 15 | [RFC 2119][]. 16 | 17 | Besedo `implementator` se v tem dokumentu razlaga kot nekoga, ki 18 | impementira `LoggerInterface` v knjižnico, ki se tiče dnevnika ali ogrodja. 19 | Uporabniki dnevnikov so navedeni kot `uporabnik`. 20 | 21 | [RFC 2119]: http://tools.ietf.org/html/rfc2119 22 | 23 | 1. Specifikacija 24 | ---------------- 25 | 26 | ### 1.1 Osnove 27 | 28 | - `LoggerInterface` izpostavlja osem metod za pisanje dnevnikov na osem 29 | [RFC 5424][] nivojev (debug, info, notice, warning, error, critical, alert, 30 | emergency). 31 | 32 | - Deveta metoda, `log`, sprejema nivo dnevnika kot prvi argument. Klicanje te 33 | metode z eno izmed konstant nivoja dnevnika MORA imeti enak rezultat kot 34 | klicanje metoda določenega nivoja. Klicanje te metode z nivojem, ki ni definiran 35 | v tej implementaciji MORA vreči `Psr\Log\InvalidArgumentException`, 36 | če implementacija ne pozna nivoja. Uporabniki NE BI SMELI uporabljati 37 | nivojev po meri brez, da bi zagotovo vedeli, da ga trenutna implementacija podpira. 38 | 39 | [RFC 5424]: http://tools.ietf.org/html/rfc5424 40 | 41 | ### 1.2 Sporočilo 42 | 43 | - Vsaka metoda sprejema niz kot sporočilo ali objekt z 44 | metodo `__toString()`. Implementatorji LAHKO imajo posebno ravnanje za poslane 45 | objekte. Če to ni primer, implementors MORAJO vezati na niz. 46 | 47 | - Sporočilo LAHKO vsebuje ograde, ki jih implementatorji LAHKO zamenjajo z 48 | vrednostmi iz kontekstnega polja. 49 | 50 | Imena ograd MORAJO biti v korespondenci s ključi konteksnega polja. 51 | 52 | Imena ograd MORAJO biti ločena z enim odpirajočim zavitim oklepajem `{` in 53 | enim zavitim zaklepajem `}`. NE SME BITI kakršnih koli praznih prostorov med 54 | ločili in imenom ograde. 55 | 56 | Imena ograd MORAJO biti sestavljena samo iz znakov `A-Z`, `a-z`, 57 | `0-9`, podčrtajev `_` in pike `.`. Uporaba ostalih znakov je 58 | rezervirana za prihajajoče spremembe specifikacij ograd. 59 | 60 | Implementatorji LAHKO uporabljajo ograde za implementacijo različnih strategij zatekanja 61 | in prevajanja dnevnikov za prikaz. Uporabniki NE BI SMELI vnaprej zatekati vrednosti 62 | ograd, saj morda ne vejo v katerem kontekstu bodo podatki prikazani. 63 | 64 | Sledi primer implementacije ogradne interpolacije 65 | ponujen samo za namene sklicevanja: 66 | 67 | ```php 68 | /** 69 | * Interpolates context values into the message placeholders. 70 | */ 71 | function interpolate($message, array $context = array()) 72 | { 73 | // build a replacement array with braces around the context keys 74 | $replace = array(); 75 | foreach ($context as $key => $val) { 76 | $replace['{' . $key . '}'] = $val; 77 | } 78 | 79 | // interpolate replacement values into the message and return 80 | return strtr($message, $replace); 81 | } 82 | 83 | // a message with brace-delimited placeholder names 84 | $message = "User {username} created"; 85 | 86 | // a context array of placeholder names => replacement values 87 | $context = array('username' => 'bolivar'); 88 | 89 | // echoes "User bolivar created" 90 | echo interpolate($message, $context); 91 | ``` 92 | 93 | ### 1.3 Kontekst 94 | 95 | - Vsaka metoda sprejema polje podatkov konteksta. To je namenjeno držanju katerihkoli 96 | tujih informacij, ki se ne ujemajo dobro v nizu. Polje lahko 97 | vključuje karkoli. Implementatorji MORAJO zagotoviti, da obravnavajo podatke konteksta s 98 | kakorkoli zanesljivosti je možno. Dana vrednost v kontekstu NE SME vreči 99 | izjeme ali dvigniti katerekoli php napake, opozorila ali obvestila. 100 | 101 | - Če je podan objekt `Exception` v kontekst podatkov, MORA biti v 102 | ključu `'exception'`. Beleženje izjem v dnevnikih je pogosti vzorec in to omogoča 103 | implementatorjem, da ekstraktirajo snop sledi iz izjeme, ko to 104 | ozadnje dnevnika omogoča. Implementatorji MORAJO še vedno zagotavljati, da ključ `'exception'` 105 | je dejansko `Exception` preden se ga uporablja kot takega, saj lahko vključuje 106 | karkoli. 107 | 108 | ### 1.4 Pomočniški razredi in vmesniki 109 | 110 | - Razred `Psr\Log\AbstractLogger` vam omogoča, da implementirate `LoggerInterface` 111 | zelo enostavno z razširitvijo in implementacijo generične `log` metode. 112 | Drugih osem metod mu posreduje sporočilo in kontekst. 113 | 114 | - Podbno z uporabo `Psr\Log\LoggerTrait` od vas samo zahteva 115 | implementacijo generične `log` metode. Bodite pozorni, da odkar lastnosti - traits ne morejo implementirati 116 | vmesnikov, morate v tem primeru še vedno narediti implementirati `LoggerInterface`. 117 | 118 | - `Psr\Log\NullLogger` je ponujen skupaj z vmesnikom. LAHKO 119 | ga uporabljajo uporabniki vmesnika, da podajo fall-back "črno luknjo" 120 | implementacije, če noben dnevnik ni podan njim. Vendar pogojno beleženje dnevnika 121 | je lahko boljši pristop, če je izdelava podatkov konteksta draga. 122 | 123 | - `Psr\Log\LoggerAwareInterface` samo vključuje 124 | `setLogger(LoggerInterface $logger)` metodo in jo ogrodja lahko uporabljajo za 125 | avtomatsko povezovanje samovoljne instance z dnevnikom. 126 | 127 | - `Psr\Log\LoggerAwareTrait` lastnost je lahko uporabljena za implementacijo ekvivalentnega 128 | vmesnika enostavno v kateremkoli razredu. Da vam dostop do `$this->logger`. 129 | 130 | - `Psr\Log\LogLevel` razred zadržuje konstante za osem nivojev dnevnika. 131 | 132 | 2. Paket 133 | -------- 134 | 135 | Vmesniki in razredi opisani in tudi pomembni razredi izjem 136 | in komplet testov za pregledovanje vaše implementacije so ponujeni kot del 137 | paketa [psr/log](https://packagist.org/packages/psr/log). 138 | 139 | 3. `Psr\Log\LoggerInterface` 140 | ---------------------------- 141 | 142 | ```php 143 | register(); 90 | * 91 | * // register the base directories for the namespace prefix 92 | * $loader->addNamespace('Foo\Bar', '/path/to/packages/foo-bar/src'); 93 | * $loader->addNamespace('Foo\Bar', '/path/to/packages/foo-bar/tests'); 94 | * 95 | * The following line would cause the autoloader to attempt to load the 96 | * \Foo\Bar\Qux\Quux class from /path/to/packages/foo-bar/src/Qux/Quux.php: 97 | * 98 | * prefixes[$prefix]) === false) { 148 | $this->prefixes[$prefix] = array(); 149 | } 150 | 151 | // retain the base directory for the namespace prefix 152 | if ($prepend) { 153 | array_unshift($this->prefixes[$prefix], $base_dir); 154 | } else { 155 | array_push($this->prefixes[$prefix], $base_dir); 156 | } 157 | } 158 | 159 | /** 160 | * Loads the class file for a given class name. 161 | * 162 | * @param string $class The fully-qualified class name. 163 | * @return mixed The mapped file name on success, or boolean false on 164 | * failure. 165 | */ 166 | public function loadClass($class) 167 | { 168 | // the current namespace prefix 169 | $prefix = $class; 170 | 171 | // work backwards through the namespace names of the fully-qualified 172 | // class name to find a mapped file name 173 | while (false !== $pos = strrpos($prefix, '\\')) { 174 | 175 | // retain the trailing namespace separator in the prefix 176 | $prefix = substr($class, 0, $pos + 1); 177 | 178 | // the rest is the relative class name 179 | $relative_class = substr($class, $pos + 1); 180 | 181 | // try to load a mapped file for the prefix and relative class 182 | $mapped_file = $this->loadMappedFile($prefix, $relative_class); 183 | if ($mapped_file) { 184 | return $mapped_file; 185 | } 186 | 187 | // remove the trailing namespace separator for the next iteration 188 | // of strrpos() 189 | $prefix = rtrim($prefix, '\\'); 190 | } 191 | 192 | // never found a mapped file 193 | return false; 194 | } 195 | 196 | /** 197 | * Load the mapped file for a namespace prefix and relative class. 198 | * 199 | * @param string $prefix The namespace prefix. 200 | * @param string $relative_class The relative class name. 201 | * @return mixed Boolean false if no mapped file can be loaded, or the 202 | * name of the mapped file that was loaded. 203 | */ 204 | protected function loadMappedFile($prefix, $relative_class) 205 | { 206 | // are there any base directories for this namespace prefix? 207 | if (isset($this->prefixes[$prefix]) === false) { 208 | return false; 209 | } 210 | 211 | // look through base directories for this namespace prefix 212 | foreach ($this->prefixes[$prefix] as $base_dir) { 213 | 214 | // replace the namespace prefix with the base directory, 215 | // replace namespace separators with directory separators 216 | // in the relative class name, append with .php 217 | $file = $base_dir 218 | . str_replace('\\', '/', $relative_class) 219 | . '.php'; 220 | 221 | // if the mapped file exists, require it 222 | if ($this->requireFile($file)) { 223 | // yes, we're done 224 | return $file; 225 | } 226 | } 227 | 228 | // never found it 229 | return false; 230 | } 231 | 232 | /** 233 | * If a file exists, require it from the file system. 234 | * 235 | * @param string $file The file to require. 236 | * @return bool True if the file exists, false if not. 237 | */ 238 | protected function requireFile($file) 239 | { 240 | if (file_exists($file)) { 241 | require $file; 242 | return true; 243 | } 244 | return false; 245 | } 246 | } 247 | ``` 248 | 249 | ### Testi enot 250 | 251 | Sledeči primer je eden izmed načinov testiranja enot za zgornji nalagalni razred: 252 | 253 | ```php 254 | files = $files; 264 | } 265 | 266 | protected function requireFile($file) 267 | { 268 | return in_array($file, $this->files); 269 | } 270 | } 271 | 272 | class Psr4AutoloaderClassTest extends \PHPUnit_Framework_TestCase 273 | { 274 | protected $loader; 275 | 276 | protected function setUp() 277 | { 278 | $this->loader = new MockPsr4AutoloaderClass; 279 | 280 | $this->loader->setFiles(array( 281 | '/vendor/foo.bar/src/ClassName.php', 282 | '/vendor/foo.bar/src/DoomClassName.php', 283 | '/vendor/foo.bar/tests/ClassNameTest.php', 284 | '/vendor/foo.bardoom/src/ClassName.php', 285 | '/vendor/foo.bar.baz.dib/src/ClassName.php', 286 | '/vendor/foo.bar.baz.dib.zim.gir/src/ClassName.php', 287 | )); 288 | 289 | $this->loader->addNamespace( 290 | 'Foo\Bar', 291 | '/vendor/foo.bar/src' 292 | ); 293 | 294 | $this->loader->addNamespace( 295 | 'Foo\Bar', 296 | '/vendor/foo.bar/tests' 297 | ); 298 | 299 | $this->loader->addNamespace( 300 | 'Foo\BarDoom', 301 | '/vendor/foo.bardoom/src' 302 | ); 303 | 304 | $this->loader->addNamespace( 305 | 'Foo\Bar\Baz\Dib', 306 | '/vendor/foo.bar.baz.dib/src' 307 | ); 308 | 309 | $this->loader->addNamespace( 310 | 'Foo\Bar\Baz\Dib\Zim\Gir', 311 | '/vendor/foo.bar.baz.dib.zim.gir/src' 312 | ); 313 | } 314 | 315 | public function testExistingFile() 316 | { 317 | $actual = $this->loader->loadClass('Foo\Bar\ClassName'); 318 | $expect = '/vendor/foo.bar/src/ClassName.php'; 319 | $this->assertSame($expect, $actual); 320 | 321 | $actual = $this->loader->loadClass('Foo\Bar\ClassNameTest'); 322 | $expect = '/vendor/foo.bar/tests/ClassNameTest.php'; 323 | $this->assertSame($expect, $actual); 324 | } 325 | 326 | public function testMissingFile() 327 | { 328 | $actual = $this->loader->loadClass('No_Vendor\No_Package\NoClass'); 329 | $this->assertFalse($actual); 330 | } 331 | 332 | public function testDeepFile() 333 | { 334 | $actual = $this->loader->loadClass('Foo\Bar\Baz\Dib\Zim\Gir\ClassName'); 335 | $expect = '/vendor/foo.bar.baz.dib.zim.gir/src/ClassName.php'; 336 | $this->assertSame($expect, $actual); 337 | } 338 | 339 | public function testConfusion() 340 | { 341 | $actual = $this->loader->loadClass('Foo\Bar\DoomClassName'); 342 | $expect = '/vendor/foo.bar/src/DoomClassName.php'; 343 | $this->assertSame($expect, $actual); 344 | 345 | $actual = $this->loader->loadClass('Foo\BarDoom\ClassName'); 346 | $expect = '/vendor/foo.bardoom/src/ClassName.php'; 347 | $this->assertSame($expect, $actual); 348 | } 349 | } 350 | -------------------------------------------------------------------------------- /accepted/sl/PSR-4-autoloader.md: -------------------------------------------------------------------------------- 1 | # Avtomatski nalagalnik 2 | 3 | Ključne besede "MORA", "NE SME", "ZAHTEVA", "PRIPOROČA", "LAHKO" in "NEOBVEZNO" 4 | v tem dokumentu se tolmačijo, kot je navedeno v 5 | [RFC 2119](http://tools.ietf.org/html/rfc2119). 6 | 7 | 8 | ## 1. Pregled 9 | 10 | Ta PSR opisuje specifikacijo za [avtomatsko nalaganje][autoloading] razrede iz poti 11 | datotek. Je polno interoperabilen in je lahko uporabljen kot dodatek h katerim koli ostalim 12 | specifikacijam avtomatskega nalagalnika, vključno s [PSR-0][]. Ta PSR tudi opisuje, kam 13 | dati datoteke, ki bodo avtomatsko naložene glede na specifikacijo. 14 | 15 | 16 | ## 2. Specifikacija 17 | 18 | 1. Izraz "razred" se sklicuje na razrede, vmesnike, lastnosti - traits in ostale podobne 19 | strukture. 20 | 21 | 2. Polno kvalificirano ime razreda ima sledečo obliko: 22 | 23 | \(\)*\ 24 | 25 | 1. Polno kvalificirano ime razreda MORA imeti ime imenskega prostora najvišjega nivoja, 26 | znano tudi kot "ime izdelovalca" oz. "vendor namespace". 27 | 28 | 2. Polno kvalificirano ime razreda ima LAHKO eno ali več imen pod-imenskih 29 | prostorov. 30 | 31 | 3. Polno kvalificirano ime razreda MORA imeti zaključno ime razreda. 32 | 33 | 4. Podčrtaji nimajo posebnega pomena v kateremkoli delu celotno 34 | kvalificiranega imena razreda. 35 | 36 | 5. Znaki abecede v polno kvalificiranem imenu razreda so LAHKO katerakoli 37 | kombinacija malih in velikih črk. 38 | 39 | 6. Vsa imena razredov MORAJO biti sklicana v stilu ločevanja malih in velikih črk. 40 | 41 | 3. Ko se nalaga datoteko, ki ustreza polno kvalificiranem imenu razreda ... 42 | 43 | 1. Sosednje serije enega ali več vodilnih imen imenskega prostora in pod-imenskega prostora, 44 | kar ne vključuje vodilnega ločila imenskih prostorov v polno kvalificiranem 45 | imenu razreda (t.i. "predpona imenskega prostora"), ustreza vsaj enemu 46 | "osnovnemu direktoriju". 47 | 48 | 2. Sosednja imena pod-imenskih prostorov za "predpono imenskega prostora" 49 | ustreza pod-direktoriju znotraj "osnovnega direktorija", kjer 50 | ločila imenskega prostora predstavljajo ločila direktorijev. Ime pod-direktorija 51 | se MORA ujemati z ločevanjem velikih in malih črk imen pod-imenskih prostorov. 52 | 53 | 3. Zaključno ime razreda ustreza imenu datoteke s končnico `.php`. 54 | Ime datoteke se MORA ujemati z imenom zaključnega razreda, ki ločuje velike in male črke. 55 | 56 | 4. Implementacije avtomatskega nalagalnika NE SMEJO vreči izjem, NE SMEJO dvigniti napak 57 | katerega koli nivoja in NE BI SMELE vrniti vrednosti. 58 | 59 | 60 | ## 3. Primeri 61 | 62 | Tabela spodaj prikazuje ustrezne poti datotek za dano polno kvalificirano 63 | ime razreda, predpono imenskega prostora in osnovni direktorij. 64 | 65 | | Polno kvalificirano ime razreda | Predpona imenskega prostora | Osnovni direktorij | Rezultat poti datoteke 66 | | ------------------------------- |-----------------------------|--------------------------|------------------------------------------- 67 | | \Acme\Log\Writer\File_Writer | Acme\Log\Writer | ./acme-log-writer/lib/ | ./acme-log-writer/lib/File_Writer.php 68 | | \Aura\Web\Response\Status | Aura\Web | /path/to/aura-web/src/ | /path/to/aura-web/src/Response/Status.php 69 | | \Symfony\Core\Request | Symfony\Core | ./vendor/Symfony/Core/ | ./vendor/Symfony/Core/Request.php 70 | | \Zend\Acl | Zend | /usr/includes/Zend/ | /usr/includes/Zend/Acl.php 71 | 72 | Na primer, za implementacije avtomatskih nalagalnikov, ki se skladajo s specifikacijo, 73 | prosimo, glejte [primer datoteke][]. Primeri implementacij NE SMEJO biti obravnavani 74 | kot del specifikacije in se LAHKO spremenijo kadarkoli. 75 | 76 | [autoloading]: http://php.net/autoload 77 | [PSR-0]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md 78 | [primer datoteke]: https://github.com/php-fig/fig-standards/blob/master/accepted/sl/PSR-4-autoloader-examples.md 79 | -------------------------------------------------------------------------------- /bylaws/001-voting-protocol.md: -------------------------------------------------------------------------------- 1 | Voting Protocol 2 | =============== 3 | 4 | 1. Only voting members may initiate a call for votes on a measure. 5 | 6 | 2. Only voting members may vote on a measure. 7 | 8 | 3. The time limit on a vote is 14 days from the time of the call for votes, or 9 | until all voting members have cast their vote, whichever comes first. Votes 10 | cast after the time limit are not valid. 11 | 12 | 4. Votes can be +1 ("in favor"), -1 ("against"), or 0 ("abstain"). 13 | 14 | 5. One-third or more of the *voting members* must vote within the time limit 15 | for the vote to be valid. This is the equivalent of establishing a quorum. For 16 | example: 17 | 18 | - If there are 20, 21, or 22 members, then 7 or more must vote within the 19 | time limit for the vote to be valid. 20 | 21 | - If there are 23, 24, or 25 members, then 8 or more must vote within the 22 | time limit for the vote to be valid. 23 | 24 | 6. The measure passes if a simple majority of the *votes cast* are "in favor". 25 | The measure does not pass otherwise. For example: 26 | 27 | - If there are 10 or 11 votes cast, 6 or more must be "in favor". 28 | 29 | - If there are 12 or 13 votes cast, 7 or more must be "in favor". 30 | 31 | 7. Measures passed are not binding. A vote "in favor" of a measure is an 32 | indication that the measure is approved, but the voting member may not be able 33 | to apply it immediately for reasons outside the purview of this group. 34 | 35 | 8. Votes on membership requests represent a special case: 36 | 37 | - Regarding point 1, they may be initiated by non-members. 38 | 39 | - Regarding point 7, it is binding on all members. 40 | 41 | * * * 42 | 43 | N.b.: "Abstain" votes are counted only for quorum, and are not counted when 44 | calculating majority. 45 | 46 | -------------------------------------------------------------------------------- /bylaws/002-psr-naming-conventions.md: -------------------------------------------------------------------------------- 1 | Naming conventions for code released by PHP-FIG 2 | =============================================== 3 | 4 | 1. Interfaces MUST be suffixed by `Interface`: e.g. `Psr\Foo\BarInterface`. 5 | 2. Abstract classes MUST be prefixed by `Abstract`: e.g. `Psr\Foo\AbstractBar`. 6 | 3. Traits MUST be suffixed by `Trait`: e.g. `Psr\Foo\BarTrait`. 7 | 4. PSR-1, 2 and 4 MUST be followed. 8 | 5. The vendor namespace MUST be `Psr`. 9 | 6. There MUST be a package/second-level namespace in relation with the PSR that 10 | covers the code. 11 | 7. Composer package MUST be named `psr/` e.g. `psr/log`. If they 12 | require an implementation as a virtual package it MUST be named 13 | `psr/-implementation` and be required with a specific version like 14 | `1.0.0`. Implementors of that PSR can then provide 15 | `"psr/-implementation": "1.0.0"` in their package to satisfy that 16 | requirement. Specification changes via further PSRs should only lead to a new 17 | tag of the `psr/` package, and an equal version bump of the 18 | implementation being required. 19 | -------------------------------------------------------------------------------- /bylaws/003-membership.md: -------------------------------------------------------------------------------- 1 | Membership 2 | ========== 3 | 4 | The membership of the PHP Framework Interoperability Group (PHP-FIG) is 5 | comprised of Member Projects. This bylaw defines the rules and rights of 6 | membership. 7 | 8 | Definitions 9 | ----------- 10 | 11 |
12 |
Member Project
13 |
14 | Any PHP project with voting rights admitted to PHP-FIG after 15 | submitting an application to the PHP-FIG mailing list under the 16 | Member Application procedure described in this bylaw. 17 |
18 |
Voting Representative
19 |
20 | Any individual granted the right to cast votes on behalf of a Member 21 | Project. 22 |
23 |
24 | 25 | Membership List 26 | --------------- 27 | 28 | The current Member Projects in PHP-FIG will be listed at the following URL: 29 | http://www.php-fig.org/ 30 | 31 | This list must also indicate the names of the current Voting Representative for 32 | each Member Project. This list must be updated for any change in the composition 33 | of Member Projects or Voting Representatives. 34 | 35 | Membership Application 36 | ---------------------- 37 | 38 | To cast votes on PHP-FIG proposals, it is required that a PHP project apply to 39 | become a Member Project. This application may be submitted by any individual who 40 | is authorised by the PHP project in question to do so. 41 | 42 | The application must be emailed to the main [php-fig mailing list][list] and 43 | is restricted to one application per email. In order to be considered, all 44 | applications must be sponsored in advance by at least one existing Voting 45 | Representative. 46 | 47 | The subject of the email must follow the following format: 48 | 49 | Membership Request: {$your_name} ({$project_name}) 50 | 51 | The body of the email should provide details of the PHP project applying for 52 | membership including its name, URL, the name of the proposed Voting 53 | Representative, the name of the Voting Representative sponsor and any other 54 | details that the individual applying on behalf of the PHP project believes are 55 | necessary to include. 56 | 57 | There must be a minimum two week period from the membership request being made 58 | before voting can begin to allow for necessary discussions. 59 | 60 | The membership application can then be voted upon by the existing Member Projects 61 | in accordance with the [Voting Protocol bylaw][voting]. PHP-FIG must perform 62 | checks to ensure that each application is valid and authorised by the PHP 63 | project that the applicant claims to act on behalf of. Once voting has completed 64 | and if the application has been deemed accepted, the PHP project will become a 65 | Member Project with immediate effect. 66 | 67 | There are no restrictions on the number of times a PHP project may apply to 68 | become a Member Project. 69 | 70 | Voting Representatives 71 | ----------------------- 72 | 73 | The votes of all Member Projects are cast by Voting Representives who have been 74 | authorised to do so by the Member Project. Each Voting Representative is chosen 75 | solely by a Member Project and their selection is not subject to the approval 76 | of PHP-FIG. A Voting Representative may be replaced by the Member Project which 77 | they represent at any time. 78 | 79 | To prevent illegal or erroneous voting, the Voting Representative must be 80 | confirmed by the Member Project to be authorised to act in such a capacity 81 | by sending an email to the main [php-fig mailing list][list]. This email 82 | may be combined with a Member Application if the applicant has sufficient 83 | authority. The other Member Projects may seek such confirmation at any time 84 | during the Voting Representative's term. 85 | 86 | A Member Project may not have more than one Voting Representative at a time. 87 | 88 | A Voting Representative may temporarily confer their voting rights onto another 89 | individual who is authorised by the Member Project which they represent. This 90 | conferral must be notified to PHP-FIG by the current Voting Representative 91 | by sending an email to the main [php-fig mailing list][list]. This email 92 | must state the name of the temporary Voting Representative and the period of 93 | time for which their temporary voting rights will remain valid. All voting 94 | rights will automatically return to the original Voting Representative at the 95 | end of the period of time stated in this email. All dates noted should reference 96 | a timezone. Where a timezone is not referenced, Coordinated Universal Time (UTC) 97 | will be assumed. 98 | 99 | If, in the judgement of PHP-FIG, a Voting Representative is acting 100 | inappropriately and to the detriment of PHP-FIG's ability to meet its 101 | objectives, a vote may be taken to request a replacement Voting Representative in 102 | accordance with the [Voting Protocol bylaw][voting] or to expel the Member 103 | Project where replacing a Voting Representative is not possible. 104 | 105 | Resignation Of Member Projects 106 | ------------------------------ 107 | 108 | A Member Project may resign from PHP-FIG in writing to the main 109 | [php-fig mailing list][list] or by stating their intention to do so on another 110 | official public channel. Once such a statement is published, a PHP project 111 | immediately ceases to be a Member Project. 112 | 113 | A former Member Project may reapply for membership at any future date. 114 | 115 | Expulsion Of Member Projects 116 | ---------------------------- 117 | 118 | A Member Project may be expelled from PHP-FIG if, in the judgement of PHP-FIG, 119 | that Member Project has not casted votes in three consecutive voting calls or all voting 120 | calls over a period no less than six months whichever constitutes the greater 121 | period of time. It is the responsibility of Member Projects to ensure that they 122 | are actively represented by a Voting Representative. 123 | 124 | A Member Project may also be expelled if their Voting Representative is subject 125 | to a replacement request from PHP-FIG but a suitable replacement is not 126 | available. 127 | 128 | The expulsion of a Member Project requires a vote in accordance with the 129 | [Voting Protocol bylaw][voting]. 130 | 131 | [list]: https://groups.google.com/forum/?fromgroups#!forum/php-fig 132 | [voting]: https://github.com/php-fig/fig-standards/blob/master/bylaws/001-voting-protocol.md 133 | -------------------------------------------------------------------------------- /bylaws/005-licensing-policies.md: -------------------------------------------------------------------------------- 1 | Licensing Policies 2 | ================== 3 | 4 | ## 1. Code 5 | 6 | 1. All PHP-FIG code must be licensed under the MIT license. 7 | 8 | 2. Code includes any pure PHP files (including but not limited to classes, 9 | functions, interfaces and procedural code), as well as any code inside of 10 | examples, tutorials, supporting documents and the PSRs themselves. 11 | 12 | 13 | ## 2. Documentation 14 | 15 | All remaining non-code items must be licensed under the Creative Commons BY 3.0 16 | license. Attribution policies will be defined in the bylaws based on the type 17 | of asset created. 18 | -------------------------------------------------------------------------------- /bylaws/006-psr-amendments.md: -------------------------------------------------------------------------------- 1 | Amendments 2 | ========== 3 | 4 | Following the rules of the [workflow bylaw], once a PSR has been "Accepted" the PSR meaning 5 | cannot change, backwards compatibility must remain at 100%, and any confusion that arises from 6 | original wording can be clarified through errata. 7 | 8 | The rules for errata are covered in the [workflow bylaw], and only allow non-backwards compatible 9 | clarification to be added to the meta document. Sometimes, modifications will be necessary in PSR 10 | document itself, and this document outlines those cases. 11 | 12 | ## 1. Deprecation and Replacement 13 | 14 | If a PSR is found to require substantive updates or errata is no longer able to clarify confusion, 15 | then the PSR must be replaced, following the workflow set out in [workflow bylaw]. 16 | 17 | The original PSR may at some point in time be deprecated, and the new PSR becomes the recommended 18 | document. Deprecation and recommendation changes must be made with a vote according to the rules 19 | of the [voting protocol], with a subject like "[VOTE] Deprecate PSR-X", at which point a 20 | superseding PSR should be specified as a recommendation. 21 | 22 | Once a vote to deprecate a PSR and supersede it with another PSR has passed, the deprecated PSR must 23 | be marked as such in the original document and a link should be placed in the body. 24 | 25 | For example, the following Markdown be placed at the very top of the relevant standard file in the 26 | official PHP-FIG GitHub repo `fig-standards`. 27 | 28 | > **Deprecated** - As of 2014-12-30 PSR-0 has been marked as deprecated. [PSR-4] is now recommended 29 | as an alternative. 30 | > [PSR-4]: http://php-fig.org/psr/psr-4 31 | 32 | 33 | ## 2. Dependencies 34 | 35 | As documents are expected to be replaced rather than amended, dependencies on 36 | other PSR's should be avoided whenever possible. For instance, the following is 37 | no longer permitted: 38 | 39 | > - Namespaces and classes MUST follow PSR-0. 40 | 41 | Instead - if a dependency is considered necessary by the working group creating it - then the following 42 | example can be used: 43 | 44 | > - Namespaces and classes MUST follow an autoloading PSR: [ [PSR-0] ]. 45 | 46 | The outer set of square brackets denote a "dependency list", which is a list of PSRs 47 | that are considered a compatible dependency. 48 | 49 | When more PSR's are added to the "dependency list" the same example would look like this: 50 | 51 | > - Namespaces and classes MUST follow an autoloading PSR: [ [PSR-0], [PSR-4] ]. 52 | 53 | New PSR's can be added to the "dependency list", but old PSR's can never be removed as this would break 54 | backwards compatability. 55 | 56 | ## 3. Acceptable Amendments 57 | 58 | Other than updating the "dependency list", there are two other potentially acceptable amendment scenarios 59 | which do not require their own special vote. 60 | 61 | ### 3.1. Annotations 62 | 63 | If Errata is added which is deemed important enough by whoever is initiating the errata vote, 64 | annotations may be placed in or near the offending line so that readers know to view the errata for 65 | more information, with a link containing an anchor to that specific piece of errata. 66 | 67 | > - Something confusing about where brackets go. [cf. [errata](foo-meta.md#errata-1-foo)] 68 | 69 | This will be done as part of the errata vote, not its own. 70 | 71 | ### 3.2. Formatting & Typos 72 | 73 | If formatting is broken for any reason then changing formatting must not be considered a 74 | change to the document. These can be merged or pushed without hesitation, as long as they 75 | don't change anything of any meaning or syntax. 76 | 77 | Some typos as trivial as a misplaced comma could have a subtle impact on meaning. Take special care not to 78 | alter backwards compatibility and create a vote if unsure. Common sense will help here. 79 | 80 | Examples: 81 | 82 | 1. HTML Tables are currently broken on php-fig.org because of the syntax used. 83 | 2. Somebody spelled something wrong and nobody spotted it for a year. 84 | 3. Problems with GitHub Markdown 85 | 86 | [workflow bylaw]: https://github.com/php-fig/fig-standards/blob/master/bylaws/004-psr-workflow.md 87 | [voting protocol]: https://github.com/php-fig/fig-standards/blob/master/bylaws/001-voting-protocol.md 88 | -------------------------------------------------------------------------------- /bylaws/es/001-protocolo-de-votacion.md: -------------------------------------------------------------------------------- 1 | Protocolo de votación 2 | ================= 3 | 4 | 1. Sólo los miembros con derecho a voto pueden iniciar una convocatoria a votación sobre una medida. 5 | 6 | 2. Sólo los miembros con derecho a voto pueden votar sobre una medida. 7 | 8 | 3. El límite de tiempo para emitir un voto es de 14 días desde la convocatoria o hasta que todos los miembros hayan emitido su voto, lo que ocurra primero. Los votos emitidos fuera de plazo no serán válidos. 9 | 10 | 4. Los votos pueden ser +1 ("A favor"), -1 ("En contra") o 0 ("Abstención"). 11 | 12 | 5. Un tercio o más de los miembros con derecho a voto deben votar dentro del límite de tiempo establecido para que la votación sea válida. Esto es equivalente a establecer un *quórum*. Por ejemplo: 13 | 14 | - Si hay 20, 21 o 22 miembros, entonces 7 o más miembros tienen que emitir el voto antes del tiempo límite para que la votación sea válida. 15 | 16 | - Si hay 23, 24 o 25 miembros, entonces 8 o más miembros tienen que emitir su voto antes del tiempo límite para que la votación sea válida. 17 | 18 | 6. Una medida será aprobada si la mayoría simple de los *votos emitidos* son "A favor". 19 | 20 | - Si hay 10 u 11 votos emitidos, 6 o más votos tienen que ser "A favor". 21 | 22 | - Si hay 12 o 13 votos emitidos, 7 o más votos tienen que ser "A favor". 23 | 24 | 7. Las medidas aprobadas no son vinculantes. Un resultado "A favor" de una medida es una indicación de que la medida ha sido aprobada, pero el miembro con derecho a voto puede no ser capaz de aplicarla de inmediato por razones ajenas a este grupo. 25 | 26 | 8. El voto de las solicitudes de adhesión representan un caso especial: 27 | 28 | - Respecto al punto 1, los que no sean miembros con derecho a voto pueden iniciar una convocatoria. 29 | 30 | - Respecto al punto 7, el resultado es vinculante para todos los miembros. 31 | 32 | * * * 33 | 34 | Nota: Los votos de "Abstención" se cuentan únicamente para el *quórum* y no contarán para calcular la mayoría. -------------------------------------------------------------------------------- /bylaws/es/002-convenciones-de-nombres-psr.md: -------------------------------------------------------------------------------- 1 | Convención de nombres para el código liberado bajo PHP-FIG 2 | =============================================== 3 | 4 | 1. Las interfaces TIENEN QUE tener el sufijo `Interface`: p.ej. `Psr\Foo\BarInterface`. 5 | 2. Las clases abstractas TIENEN QUE llevar el prefijo `Abstract`: p.ej. `Psr\Foo\AbstractBar`. 6 | 3. Los traits TIENEN QUE tener el sufijo `Trait`: p.ej. `Psr\Foo\BarTrait`. 7 | 4. PSR-0, 1 y 2 TIENEN QUE cumplirse. 8 | 5. El nombre de proveedor TIENE QUE ser `Psr`. 9 | 6. TIENE QUE haber un espacio de nombres del paquete de segundo nivel en relación al PSR que engloba el código. 10 | 7. El paquete Composer TIENE QUE llamarse `psr/` p.ej. `psr/log`. Si necesita una implementación como paquete virtual, éste TIENE QUE nombrarse `psr/-implementation` y requiere especificar una versión como `1.0.0`. Los implementadores de PSR pueden proveer `"psr/-implementation":"1.0.0"` en su paquete para satisfacer este requerimiento. Los cambios en la especificación a través de los PSRs deben llevar a una nueva etiqueta del paquete `psr/`, y requiere una versión ajustada a la aplicación. -------------------------------------------------------------------------------- /bylaws/sl/001-voting-protocol.md: -------------------------------------------------------------------------------- 1 | Glasovalni protokol 2 | =================== 3 | 4 | 1. Samo člani glasovanja lahko sprožijo klic za glasovanje na merjenju. 5 | 6 | 2. Samo člani glasovanja lahko glasujejo na merjenju. 7 | 8 | 3. Časovna omejitev na glasovanju je 14 dni od časa klica za glasovanje, ali 9 | dokler niso vsi člani glasovanja oddali svojega glasu, karkoli pride prej. Oddaja 10 | glasov po časovni omejitvi ni veljavna. 11 | 12 | 4. Glasovi so lahko +1 ("za"), -1 ("proti"), ali 0 ("vzdržani"). 13 | 14 | 5. Ena tretjina ali več *članov glasovanja* morajo glasovati znotraj časovne omejitve, 15 | da je glasovanje veljavno. To ustreza sklepčni ustanovitvi. Na 16 | primer: 17 | 18 | - Če je 20, 21, ali 22 članov, potem mora 7 ali več glasovati 19 | znotraj časovne omejitve, da je glasovanje veljavno. 20 | 21 | - Če je 23, 24, ali 25 članov, potem mora 8 ali več glasovati znotraj 22 | časovne omejitve, da je glasovanje veljavno. 23 | 24 | 6. Merjenje gre skozi, če je enostavna večina *oddanih glasov* "za". 25 | To merjenje drugače ne gre skozi. Na primer: 26 | 27 | - Če je 10 ali 11 oddanih glasov, 6 ali več jih mora biti "za". 28 | 29 | - Če je oddanih 12 ali 13 glasov, 7 ali več jih mora biti "za". 30 | 31 | 7. Merjenje, ki gre skozi niso obvezujoča. Glas "za" merjenja je 32 | pokazatelj, da je merjenje odobreno, vendar ga član merjenja lahko ni uspel 33 | uporabiti takoj zaradi razlogov izven klavzule te skupine. 34 | 35 | 8. Glasovi o članstvu zahtevajo predstavitev posebnega primera: 36 | 37 | - Glede točke 1, so lahko začeti s strani ne-članov. 38 | 39 | - Glede točke 7, je obvezujoče za vse člane. 40 | 41 | * * * 42 | 43 | N.b.: "Vzdržani" glasovi so šteti samo za sklepčnost in niso šteti, ko 44 | se šteje večino. 45 | 46 | -------------------------------------------------------------------------------- /bylaws/sl/002-psr-naming-conventions.md: -------------------------------------------------------------------------------- 1 | Konvencije poimenovanja za kodo izdano pod PHP-FIG 2 | ================================================== 3 | 4 | 1. Vmesniki MORAJO imeti pripono `Interface`: npr. `Psr\Foo\BarInterface`. 5 | 2. Abstraktni razredi MORAJO imeti predpono `Abstract`: npr. `Psr\Foo\AbstractBar`. 6 | 3. Lastnosti oz. t.i. Traits MORAJO imeti pripono `Trait`: npr. `Psr\Foo\BarTrait`. 7 | 4. PSR-0, 1 in 2 SE MORA upoštevati. 8 | 5. Imenski prostor izdelovalca MORA biti `Psr`. 9 | 6. Biti MORA paket/drugi-nivo imenski prostor v povezavi s PSR, ki 10 | pokriva kodo. 11 | 7. Composer paket MORA biti imenovan `psr/` npr. `psr/log`. Če 12 | se zahteva implementacija kot virtualni paket MORA biti imenovan 13 | `psr/-implementation` in je zahtevano z določeno verzijo kot 14 | `1.0.0`. Implementatorji tega PSR lahko potem ponudijo 15 | `"psr/-implementation": "1.0.0"` v njihovem paketu, da zadostijo tej 16 | zahtevi. Spremembe specifikacije preko nadaljnih PSR-jev bi morale voditi samo v novo 17 | značko `psr/` paketa in enako izdajo verzije 18 | implementacije, ki se zahteva. 19 | -------------------------------------------------------------------------------- /bylaws/sl/003-membership.md: -------------------------------------------------------------------------------- 1 | članstvo 2 | ======== 3 | 4 | Članstvo PHP ogrodij interoperabilne skupine (PHP-FIG) je 5 | sestavljeno iz projektov članov. Ta organiziranost definira pravila in pravice 6 | članstva. 7 | 8 | Definicije 9 | ---------- 10 | 11 |
12 |
Member Project
13 |
14 | Any PHP project with voting rights admitted to PHP-FIG after 15 | submitting an application to the PHP-FIG mailing list under the 16 | Member Application procedure described in this bylaw. 17 |
18 |
Voting Representative
19 |
20 | Any individual granted the right to cast votes on behalf of a Member 21 | Project. 22 |
23 |
24 | 25 | Seznam članstva 26 | --------------- 27 | 28 | Trenutni projekti članov v PHP-FIG bodo na seznamu na sledečem URL-ju: 29 | http://www.php-fig.org/ 30 | 31 | Ta seznam mora tudi navajati imena trenutnih predstavnikov glasovanja za 32 | vsak projekt člana. Ta seznam mora biti posodobljen za vsako spremembo v sestavu 33 | projektov članov ali predstavnikov glasovanja. 34 | 35 | Aplikacija članstva 36 | ------------------- 37 | 38 | Za oddajo glasov za predloge PHP-FIG je potrebno, da jih PHP projekt uporablja, da 39 | postane projekt člana. Ta aplikacija je lahko poslana kateremukoli posamezniku, ki 40 | je pooblaščen s strani PHP projekta v vprašanju, da to naredi. 41 | 42 | Aplikacija mora biti poslana po e-pošti na glavno [php-fig-mailing list][list] in 43 | je omejena na eno aplikacijo na e-pošto. Da se jo upošteva, morajo biti 44 | vse aplikacije sponzorirane vnaprej s strani vsaj enega obstoječega predstavnika 45 | glasovanja. 46 | 47 | Predmed e-pošte mora slediti sledeči obliki: 48 | 49 | Membership Request: {$your_name} ({$project_name}) 50 | 51 | Telo sporočila e-pošte bi moralo ponujati podrobnosti PHP projekta, ki zaprosi za 52 | članstvo, vključno njegovo ime, URL, ime predlaganega predstavnika 53 | glasovanja, ime sponzorja predstavnika glasovanja in katerekoli druge 54 | podrobnosti, ki jih posameznik uporablja v imenu PHP projekta in misli, da 55 | so potrebne biti vključene. 56 | 57 | Biti mora vsaj dvo-tedensko obdobje od zahtevka članstva 58 | preden se glasovanje lahko prične, da se omogoči vse potrebne razprave. 59 | 60 | Za člansko aplikacijo se nato lahko glasuje s strani obstoječih članskih projektov 61 | v skladu z [Aktom glasovalnega protokola][voting]. PHP-FIG mora opravljati 62 | preglede, da zagotovi, da je vsaka aplikacija veljavna in pooblaščena s strani PHP 63 | projekta, za katerega vlagatelj trdi ukrepanja v njegovem imenu. Ko je glasovanje končano 64 | in če je bila aplikacija šteta za sprejeto, bo PHP postal 65 | članski projekt s takojšnjim učinkom. 66 | 67 | Ni nobenih omejitev na število kolikokrat lahko PHP projekt zaprosi, 68 | da postane članski projekt. 69 | 70 | Predstavniki glasovanja 71 | ----------------------- 72 | 73 | Glasove vseh članskih projektov oddajo predstavniki glasovanja, ki so bili 74 | za to pooblaščeni s strani članskega projekta. Vsak predstavnik glasovanja je izbran 75 | izključno s strani članskega projetka in njihova izbira ni predmet odobritve 76 | PHP-FIG. Predstavnika glasovanja lahko zamenja članski projekt, ki 77 | ga kadarkoli predstavljajo. 78 | 79 | Da se prepreči nelegalno in napačno glasovanje, morajo biti predstavniki glasovanja 80 | potrjeni s strani članskega projekta, da pooblaščeno ravna v primerih kot 81 | je pošiljanje e-pošte na glavno [php-fig mailing list][list]. Ta e-pošta 82 | se lahko združuje s člansko aplikacijo, če vlagatelj ima ustrezno 83 | pooblaščenost. Ostali članski projekti lahko poiščejo potrditev kadarkoli 84 | med obdobjem predstavnika glasovanja. 85 | 86 | Članski projekt naj ne bi imel več kot enega predstavnika glasovanja naenkrat. 87 | 88 | Predstavnik glasovanja lahko začasno podeli svojo pravico glasovanja drugemu 89 | posamezniku, ki je pooblaščen s strani članskega projekta, ki ga predstavlja. Ta 90 | podelitev mora biti obveščena na PHP-FIG s strani predstavnka glasovanja 91 | s poslano e-pošto na glavno [php-fig mailing list][list]. Ta e-pošta 92 | mora navesti ime začasnega predstavnika glasovanja in časovno 93 | obdobje za katerega bodo njegove začasne glasovalne pravice ostale veljavne. Vse glasovalne 94 | pravice bodo avtomatsko vrnjene prvotnemu predstavniku glasovanja na 95 | koncu časovnega obdobja navedenega v tej e-pošti. Vsi datumi, ki so zapisani bi morali 96 | navesti časovno območje. Kjer časovno območje ni sklicano, se predpostavlja, da gre za 97 | univerzalni koordinirani čas (UTC). 98 | 99 | Če pri sodbi PHP-FIG, predstavnik glasovanja deluje 100 | neustrezno in v škodo PHP-FIG zmožnosti, da zadosti njegovim 101 | ciljem, se lahko glasuje za zahtevek o zamenjavi člana glasovanja v 102 | skladu z [aktom glasovalnega protokola][voting] ali izključitvi članskega 103 | projekta, kjer zamenjava predstavnika glasovanja ni možna. 104 | 105 | Odstop članov projekta 106 | ---------------------- 107 | 108 | Članski projekt lahko odstopi iz PHP-FIG v pisni obliki glavni 109 | [php-fig mailing list][list] ali z izjavo njihovega namena za to na drugem 110 | uradnem javnem kanalu. Enkrat ko je taka izjava objavljena, PHP projekt 111 | nemudoma preneha biti članski projekt. 112 | 113 | Nekdanju članski projekt lahko ponovno zaprosi za članstvo v katerih koli prihodnjih obdobjih. 114 | 115 | Izključitev članskih projektov 116 | ------------------------------ 117 | 118 | Članski projekt je lahko izključen iz PHP-FIG, če pri sodbi PHP-FIG 119 | ta članski projekt ni oddal glasov v treh zaporednih klicih glasovanja ali vseh klicih 120 | glasovanja v obdobju ne manj kot šest mesecev, karkoli je zaporedno daljše 121 | časovno obdobje. Gre za odgovornost članskega projekta, da zagotovi, da so 122 | aktivno predstavljeni s strani predstavnika glasovanja. 123 | 124 | Članski projekt je lahko tudi izključen, če je njihov predstavnik glasovanja predmet 125 | zahtevka zamenjave iz PHP-FIG, vendar primerna zamenjava ni 126 | na voljo. 127 | 128 | Izključitev članskega projekta zahteva glasovanje v skladu z 129 | [aktom glasovalnega protokola][voting]. 130 | 131 | [list]: https://groups.google.com/forum/?fromgroups#!forum/php-fig 132 | [voting]: https://github.com/php-fig/fig-standards/blob/master/bylaws/001-voting-protocol.md 133 | -------------------------------------------------------------------------------- /bylaws/sl/005-licensing-policies.md: -------------------------------------------------------------------------------- 1 | Politike licenciranja 2 | ===================== 3 | 4 | ## 1. Koda 5 | 6 | 1. Vsa PHP-FIG koda mora biti licencirana pod licenco MIT. 7 | 8 | 2. Koda vključuje katerekoli čiste PHP datoteke (vključno vendar ni omejeno na razrede, 9 | funkcije, vmesnike in proceduralno kodo), kot tudi katerokoli kodo znotraj 10 | primerov, vodičev, dokazil in samih PSR-jev. 11 | 12 | 13 | ## 2. Dokumentacija 14 | 15 | Vsi preostali elementi ne-kode morajo biti licencirani pod licenco Creative Commons 16 | BY 3.0. Pripisovanje politike bo definirano v aktih osnovanih na ustvrjenem tipu 17 | in sredstvu. 18 | -------------------------------------------------------------------------------- /bylaws/sl/006-psr-amendments.md: -------------------------------------------------------------------------------- 1 | Predlogi sprememb 2 | ================= 3 | 4 | Pri sledenju pravil [akta poteka dela][bylaw], ko je enkrat PSR bil "sprejet", se pomen PSR-ja 5 | ne more spremeniti, združljivost za nazaj mora ostati 100% in kakršna koli zmeda, ki nastane iz 6 | originalnega pomena, je lahko razjasnjena preko popravka. 7 | 8 | Pravila za popravke so pokrita v [aktu poteka dela][bylaw] in samo dovoljujejo združjive ne za nazaj 9 | razjasnitve, da se dodajo k meta dokumentu. Včasih bodo spremembe potrebne v samem PSR 10 | dokumentu in ta dokument obriše te primere. 11 | 12 | ## 1. Opustitev in zamenjava 13 | 14 | Če se za PSR ugotovi, da potrebuje vsebinske posodobitve ali popravke, ni več zmožen razjasniti zmedo, 15 | zato mora biti PSR zamenjan in slediti poteku dela določenega v [aktu poteka dela][bylaw]. 16 | 17 | Originalni PSR je lahko na določeni točki obdobja opuščen in novi PSR postane priporočljiv 18 | dokument. Opuščanje in priporočene spremembe morajo biti narejene z glasovanjem glede na pravila 19 | [glasovalnega protokola], z naslovom kot je "[VOTE] Deprecate PSR-X", kjer 20 | bi moral nadomestni PSR biti specificiran kot priporočilo. 21 | 22 | Ko je enkrat glasovanje opravljeno za opustitev PSR-ja in se ga nadomesti z drugim PSR, mora opuščeni PSR 23 | biti označen kot tak v originalnem dokumentu in povezava bi morala biti postavljena v telo. 24 | 25 | Na primer, sledeči Markdown je postavljen na sam vrh pomembne standardne datoteke v 26 | uradnem PHP-FIG GitHub repozitoriju `fig-standards`. 27 | 28 | > **Deprecated** - As of 2014-12-30 PSR-0 has been marked as deprecated. [PSR-4] is now recommended 29 | as an alternative. 30 | > [PSR-4]: http://php-fig.org/psr/psr-4 31 | 32 | 33 | ## 2. Odvisnosti 34 | 35 | Kot se za dokumente pričakuje, da se jih zamenja namesto spremeni, bi se moralo odvisnostim 36 | na ostale PSR-je izogibati, kadarkoli je možno. Na primer, sledeče 37 | ni več dovoljeno: 38 | 39 | > - Imenski prostori in razredi MORAJO slediti PSR-0. 40 | 41 | Namesto - če se smatra za odvisnost nujno s strani delovne skupine, ki jo je ustvarila - potem je sledeči 42 | primer lahko uporabljen: 43 | 44 | > - Namespaces and classes MUST follow an autoloading PSR: [ [PSR-0] ]. 45 | 46 | Zunanji set oglatih oklepajev označuje "seznam odvisnosti", ki je seznam PSR-jev, 47 | ki štejejo za združljivo odvisnost. 48 | 49 | Ko je več PSR-jev dodanih k "seznamu odvisnosti", bi enak primer izgledal takole: 50 | 51 | > - Namespaces and classes MUST follow an autoloading PSR: [ [PSR-0], [PSR-4] ]. 52 | 53 | Nove PSR-je se lahko doda k "seznamu odvisnosti", vendar starih PSR-jev se nikoli ne odstranja, saj bi to polomilo 54 | združljivost za nazaj. 55 | 56 | ## 3. Sprejemljive spremembe 57 | 58 | Drugače kot posodabljanje "seznama odvisnosti", obstajata dva druga potencialno sprejemljiva scenarija predloga sprememb, 59 | ki ne zahtevata njihove lastnega posebnega glasovanja. 60 | 61 | ### 3.1. Zaznamki 62 | 63 | Če so dodani popravki, ki štejejo za dovolj pomembne za kogarkoli, ki začne glasovanje za popravke, 64 | se zaznamke lahko doda v ali blizu kršene vrstice, da bralci vedo pogledati popravke za 65 | več informacij s povezavo, ki vključuje sidro na tisti določeni del popravka. 66 | 67 | > - Nekaj zmedenega o tem, kam morajo iti zaviti oklepaji. [cf. [errata](foo-meta.md#errata-1-foo)] 68 | 69 | To bo urejeno kot del glasovanja o popravkih in ne na svojem. 70 | 71 | ### 3.2. Oblikovanje & tipkarske napake 72 | 73 | Če je oblikovanje polomljeno zaradi katerega koli razloga, potem spreminjanje oblikovanja ne sme biti smatrano za 74 | spremembo dokumenta. Te so lahko združeni ali poslani brez oklevanja, dokler 75 | ne spremenijo ničesar kateregakoli pomena ali sintakse. 76 | 77 | Nekaj trivialnih tipkarskih napak, kot je napačno postavljena vejica imajo subtilen vpliv na pomen. Bodite posebej pozorni, da 78 | ne spremenite združljivosti za nazaj in izdelate glasovanje, če niste prepričani. Razum bo tam pomagal. 79 | 80 | Primeri: 81 | 82 | 1. HTML tabele so trenutno zlomljene na php-fig.org zaradi sintakse, ki je uporabljena. 83 | 2. Nekdo je nekaj napačno črkoval in nihče ni tega opazil leto dni. 84 | 3. Problemi z GitHub Markdown 85 | 86 | [bylaw]: https://github.com/php-fig/fig-standards/blob/master/bylaws/004-psr-workflow.md 87 | [glasovalnega protokola]: https://php-fig/philsturgeon/fig-standards/blob/master/bylaws/001-voting-protocol.md 88 | -------------------------------------------------------------------------------- /index.md: -------------------------------------------------------------------------------- 1 | # PHP Standard Recommendations 2 | 3 | According to the [PSR Workflow Bylaw](https://github.com/php-fig/fig-standards/blob/master/bylaws/004-psr-workflow.md) each PSR has a status as it is being worked on. Once a proposal has passed the Entrance Vote it will be listed here as "Draft". Unless a PSR is marked as "Accepted" it is subject to change. Draft can change drastically, but Review will only have minor changes. 4 | 5 | ## Index by Status 6 | 7 | ### Accepted 8 | 9 | | Num | Title | Editor | Coordinator | Sponsor | 10 | |:---:|--------------------------------|-------------------------|---------------|----------------| 11 | | 0 | [Autoloading Standard][psr0] | _N/A_ | _N/A_ | _N/A_ | 12 | | 1 | [Basic Coding Standard][psr1] | _N/A_ | _N/A_ | _N/A_ | 13 | | 2 | [Coding Style Guide][psr2] | _N/A_ | _N/A_ | _N/A_ | 14 | | 3 | [Logger Interface][psr3] | Jordi Boggiano | _N/A_ | _N/A_ | 15 | | 4 | [Autoloading Standard][psr4] | Paul M. Jones | Phil Sturgeon | Larry Garfield | 16 | | 7 | [HTTP Message Interface][psr7] | Matthew Weier O'Phinney | Beau Simensen | Paul M. Jones | 17 | 18 | ### Voting 19 | 20 | | Num | Title | Editor | Coordinator | Sponsor | 21 | |:---:|--------------------------------|-------------------------|---------------|-------------| 22 | 23 | ### Review 24 | 25 | | Num | Title | Editor | Coordinator | Sponsor | 26 | |:---:|--------------------------------|-------------------------|----------------|---------------| 27 | | 6 | [Caching Interface][psr6] | Larry Garfield | Paul Dragoonis | Pádraic Brady | 28 | 29 | ### Draft 30 | 31 | | Num | Title | Editor(s) | Coordinator | Sponsor | 32 | |:---:|--------------------------------------|--------------------------------|----------------|-------------------| 33 | | 5 | [PHPDoc Standard][psr5] | Mike van Riel | Phil Sturgeon | Donald Gilbert | 34 | | 8 | [Huggable Interface][psr8] | Larry Garfield | Cal Evans | Paul M. Jones | 35 | | 9 | [Security Disclosure][psr9] | Lukas Kahwe Smith | Korvin Szanto | Larry Garfield | 36 | | 10 | [Security Advisories][psr10] | Lukas Kahwe Smith | Larry Garfield | Korvin Szanto | 37 | | 11 | [Container Interface][psr11] | Matthieu Napoli, David Négrier | Paul M. Jones | Jeremy Lindblom | 38 | | 12 | [Extended Coding Style Guide][psr12] | Michael Cullum | Korvin Szanto | Alexander Makarov | 39 | 40 | ## Numerical Index 41 | 42 | | Status | Num | Title | Editor(s) | Coordinator | Sponsor | 43 | |--------|:---:|--------------------------------------|--------------------------------|----------------|-------------------| 44 | | A | 0 | [Autoloading Standard][psr0] | _N/A_ | _N/A_ | _N/A_ | 45 | | A | 1 | [Basic Coding Standard][psr1] | _N/A_ | _N/A_ | _N/A_ | 46 | | A | 2 | [Coding Style Guide][psr2] | _N/A_ | _N/A_ | _N/A_ | 47 | | A | 3 | [Logger Interface][psr3] | Jordi Boggiano | _N/A_ | _N/A_ | 48 | | A | 4 | [Autoloading Standard][psr4] | Paul M. Jones | Phil Sturgeon | Larry Garfield | 49 | | D | 5 | [PHPDoc Standard][psr5] | Mike van Riel | Phil Sturgeon | Donald Gilbert | 50 | | R | 6 | [Caching Interface][psr6] | Larry Garfield | Paul Dragoonis | Pádraic Brady | 51 | | A | 7 | [HTTP Message Interface][psr7] | Matthew Weier O'Phinney | Beau Simensen | Paul M. Jones | 52 | | D | 8 | [Huggable Interface][psr8] | Larry Garfield | Cal Evans | Paul M. Jones | 53 | | D | 9 | [Security Disclosure][psr9] | Lukas Kahwe Smith | Korvin Szanto | Larry Garfield | 54 | | D | 10 | [Security Advisories][psr10] | Lukas Kahwe Smith | Larry Garfield | Korvin Szanto | 55 | | D | 11 | [Container Interface][psr11] | Matthieu Napoli, David Négrier | Paul M. Jones | Jeremy Lindblom | 56 | | D | 12 | [Extended Coding Style Guide][psr12] | Michael Cullum | Korvin Szanto | Alexander Makarov | 57 | 58 | _**Legend:** A = Accepted | D = Draft | R = Review | V = Voting | X = Rejected_ 59 | 60 | [psr0]: /psr/psr-0/ 61 | [psr1]: /psr/psr-1/ 62 | [psr2]: /psr/psr-2/ 63 | [psr3]: /psr/psr-3/ 64 | [psr4]: /psr/psr-4/ 65 | [psr5]: https://github.com/phpDocumentor/fig-standards/tree/master/proposed 66 | [psr6]: https://github.com/php-fig/fig-standards/blob/master/proposed/cache.md 67 | [psr7]: /psr/psr-7/ 68 | [psr8]: https://github.com/php-fig/fig-standards/blob/master/proposed/psr-8-hug/psr-8-hug.md 69 | [psr9]: https://github.com/php-fig/fig-standards/blob/master/proposed/security-disclosure-publication.md 70 | [psr10]: https://github.com/php-fig/fig-standards/pull/473 71 | [psr11]: https://github.com/container-interop/fig-standards/blob/master/proposed/container.md 72 | [psr11]: https://github.com/container-interop/fig-standards/blob/master/proposed/container.md 73 | [psr12]: https://github.com/php-fig/fig-standards/blob/master/proposed/extended-coding-style-guide.md 74 | -------------------------------------------------------------------------------- /proposed/.placeholder: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/async-interop/fig-standards/de32aeb2e1c6e942dc3064c4c31c747877fb1114/proposed/.placeholder -------------------------------------------------------------------------------- /proposed/cache-meta.md: -------------------------------------------------------------------------------- 1 | PSR-Cache Meta Document 2 | =================== 3 | 4 | 1. Summary 5 | ---------- 6 | 7 | Caching is a common way to improve the performance of any project, making 8 | caching libraries one of the most common features of many frameworks and 9 | libraries. This has lead to a situation where many libraries roll their own 10 | caching libraries, with various levels of functionality. These differences are 11 | causing developers to have to learn multiple systems which may or may not 12 | provide the functionality they need. In addition, the developers of caching 13 | libraries themselves face a choice between only supporting a limited number 14 | of frameworks or creating a large number of adapter classes. 15 | 16 | 17 | 2. Why Bother? 18 | -------------- 19 | 20 | A common interface for caching systems will solve these problems. Library and 21 | framework developers can count on the caching systems working the way they're 22 | expecting, while the developers of caching systems will only have to implement 23 | a single set of interfaces rather than a whole assortment of adapters. 24 | 25 | Moreover, the implementation presented here is designed for future extensibility. 26 | It allows a variety of internally-different but API-compatible implementations 27 | and offers a clear path for future extension by later PSRs or by specific 28 | implementers. 29 | 30 | Pros: 31 | * A standard interface for caching allows free-standing libraries to support 32 | caching of intermediary data without effort; they may simply (optionally) depend 33 | on this standard interface and leverage it without being concerned about 34 | implementation details. 35 | * Commonly developed caching libraries shared by multiple projects, even if 36 | they extend this interface, are likely to be more robust than a dozen separately 37 | developed implementations. 38 | 39 | Cons: 40 | * Any interface standardization runs the risk of stifling future innovation as 41 | being "not the Way It's Done(tm)". However, we believe caching is a sufficiently 42 | commoditized problem space that the extension capability offered here mitigates 43 | any potential risk of stagnation. 44 | 45 | 3. Scope 46 | -------- 47 | 48 | ## 3.1 Goals 49 | 50 | * A common interface for basic and intermediate-level caching needs. 51 | * A clear mechanism for extending the specification to support advanced features, 52 | both by future PSRs or by individual implementations. This mechanism must allow 53 | for multiple independent extensions without collision. 54 | 55 | ## 3.2 Non-Goals 56 | 57 | * Architectural compatibility with all existing cache implementations. 58 | * Advanced caching features such as namespacing or tagging that are used by a 59 | minority of users. 60 | 61 | 4. Approaches 62 | ------------- 63 | 64 | ### 4.1 Chosen Approach 65 | 66 | This specification adopts a "repository model" or "data mapper" model for caching 67 | rather than the more traditional "expire-able key-value" model. The primary 68 | reason is flexibility. A simple key/value model is much more difficult to extend. 69 | 70 | The model here mandates the use of a CacheItem object, which represents a cache 71 | entry, and a Pool object, which is a given store of cached data. Items are 72 | retrieved from the pool, interacted with, and returned to it. While a bit more 73 | verbose at times it offers a good, robust, flexible approach to caching, 74 | especially in cases where caching is more involved than simply saving and 75 | retrieving a string. 76 | 77 | Most method names were chosen based on common practice and method names in a 78 | survey of member projects and other popular non-member systems. 79 | 80 | Pros: 81 | 82 | * Flexible and extensible 83 | * Allows a great deal of variation in implementation without violating the interface 84 | * Does not implicitly expose object constructors as a pseudo-interface. 85 | 86 | Cons: 87 | 88 | * A bit more verbose than the naive approach 89 | 90 | Examples: 91 | 92 | Some common usage patterns are shown below. These are non-normative but should 93 | demonstrate the application of some design decisions. 94 | 95 | ```php 96 | /** 97 | * Gets a list of available widgets. 98 | * 99 | * In this case, we assume the widget list changes so rarely that we want 100 | * the list cached forever until an explicit clear. 101 | */ 102 | function get_widget_list() 103 | { 104 | $pool = get_cache_pool('widgets'); 105 | $item = $pool->getItem('widget_list'); 106 | if (!$item->isHit()) { 107 | $value = compute_expensive_widget_list(); 108 | $item->set($value); 109 | $pool->save($item); 110 | } 111 | return $item->get(); 112 | } 113 | ``` 114 | 115 | ```php 116 | /** 117 | * Caches a list of available widgets. 118 | * 119 | * In this case, we assume a list of widgets has been computed and we want 120 | * to cache it, regardless of what may already be cached. 121 | */ 122 | function save_widget_list($list) 123 | { 124 | $pool = get_cache_pool('widgets'); 125 | $item = $pool->getItem('widget_list'); 126 | $item->set($list); 127 | $pool->save($item); 128 | } 129 | ``` 130 | 131 | ```php 132 | /** 133 | * Clears the list of available widgets. 134 | * 135 | * In this case, we simply want to remove the widget list from the cache. We 136 | * don't care if it was set or not; the post condition is simply "no longer set". 137 | */ 138 | function clear_widget_list() 139 | { 140 | $pool = get_cache_pool('widgets'); 141 | $pool->deleteItems(['widget_list']); 142 | } 143 | ``` 144 | 145 | ```php 146 | /** 147 | * Clears all widget information. 148 | * 149 | * In this case, we want to empty the entire widget pool. There may be other 150 | * pools in the application that will be unaffected. 151 | */ 152 | function clear_widget_cache() 153 | { 154 | $pool = get_cache_pool('widgets'); 155 | $pool->clear(); 156 | } 157 | ``` 158 | 159 | ```php 160 | /** 161 | * Load widgets. 162 | * 163 | * We want to get back a list of widgets, of which some are cached and some 164 | * are not. This of course assumes that loading from the cache is faster than 165 | * whatever the non-cached loading mechanism is. 166 | * 167 | * In this case, we assume widgets may change frequently so we only allow them 168 | * to be cached for an hour (3600 seconds). We also cache newly-loaded objects 169 | * back to the pool en masse. 170 | * 171 | * Note that a real implementation would probably also want a multi-load 172 | * operation for widgets, but that's irrelevant for this demonstration. 173 | */ 174 | function load_widgets(array $ids) 175 | { 176 | $pool = get_cache_pool('widgets'); 177 | $keys = array_map(function($id) { return 'widget.' . $id; }, $ids); 178 | $items = $pool->getItems($keys); 179 | 180 | $widgets = array(); 181 | foreach ($items as $key => $item) { 182 | if ($item->isHit()) { 183 | $value = $item->get(); 184 | } 185 | else { 186 | $value = expensive_widget_load($id); 187 | $item->set($value, 3600); 188 | $pool->saveDeferred($item, true); 189 | } 190 | $widget[$value->id()] = $value; 191 | } 192 | $pool->commit(); // If no items were deferred this is a no-op. 193 | 194 | return $widgets; 195 | } 196 | ``` 197 | 198 | ```php 199 | /** 200 | * This examples reflects functionality that is NOT included in this 201 | * specification, but is shown as an example of how such functionality MIGHT 202 | * be added by extending implementations. 203 | */ 204 | 205 | 206 | interface TaggablePoolInterface extends Psr\Cache\CachePoolInterface 207 | { 208 | /** 209 | * Clears only those items from the pool that have the specified tag. 210 | */ 211 | clearByTag($tag); 212 | } 213 | 214 | interface TaggableItemInterface extends Psr\Cache\CacheItemInterface 215 | { 216 | public function setTags(array $tags); 217 | } 218 | 219 | /** 220 | * Caches a widget with tags. 221 | */ 222 | function set_widget(TaggablePoolInterface $pool, Widget $widget) 223 | { 224 | $key = 'widget.' . $widget->id(); 225 | $item = $pool->getItem($key); 226 | 227 | $item->setTags($widget->tags()); 228 | $item->set($widget); 229 | $pool->save($item); 230 | } 231 | ``` 232 | 233 | ### 4.2 Alternative: "Weak item" approach 234 | 235 | A variety of earlier drafts took a simpler "key value with expiration" approach, 236 | also known as a "weak item" approach. In this model, the "Cache Item" object 237 | was really just a dumb array-with-methods object. Users would instantiate it 238 | directly, then pass it to a cache pool. While more familiar, that approach 239 | effectively prevented any meaningful extension of the Cache Item. It effectively 240 | made the Cache Item's constructor part of the implicit interface, and thus 241 | severely curtailed extensibility or the ability to have the cache item be where 242 | the intelligence lives. 243 | 244 | In a poll conducted in June 2013, most participants showed a clear preference for 245 | the more robust if less conventional "Strong item" / repository approach, which 246 | was adopted as the way forward. 247 | 248 | Pros: 249 | * More traditional approach. 250 | 251 | Cons: 252 | * Less extensible or flexible. 253 | 254 | ### 4.3 Alternative: "Naked value" approach 255 | 256 | Some of the earliest discussions of the Cache spec suggested skipping the Cache 257 | Item concept all together and just reading/writing raw values to be cached. 258 | While simpler, it was pointed out that made it impossible to tell the difference 259 | between a cache miss and whatever raw value was selected to represent a cache 260 | miss. That is, if a cache lookup returned NULL it's impossible to tell if there 261 | was no cached value or if NULL was the value that had been cached. (NULL is a 262 | legitimate value to cache in many cases.) 263 | 264 | Most more robust caching implementations we reviewed -- in particular the Stash 265 | caching library and the home-grown cache system used by Drupal -- use some sort 266 | of structured object on `get` at least to avoid confusion between a miss and a 267 | sentinel value. Based on that prior experience FIG decided that a naked value 268 | on `get` was impossible. 269 | 270 | ### 4.4 Alternative: ArrayAccess Pool 271 | 272 | There was a suggestion to make a Pool implement ArrayAccess, which would allow 273 | for cache get/set operations to use array syntax. That was rejected due to 274 | limited interest, limited flexibility of that approach (trivial get and set with 275 | default control information is all that's possible), and because it's trivial 276 | for a particular implementation to include as an add-on should it desire to 277 | do so. 278 | 279 | 5. People 280 | --------- 281 | 282 | ### 5.1 Editor 283 | 284 | * Larry Garfield 285 | 286 | ### 5.2 Sponsors 287 | 288 | * Paul Dragoonis, PPI Framework (Coordinator) 289 | * Pádraic Brady, Zend Framework 290 | 291 | ### 5.3 Contributors 292 | 293 | * Robert Hafner 294 | 295 | 6. Votes 296 | -------- 297 | 298 | 299 | 7. Relevant Links 300 | ----------------- 301 | 302 | _**Note:** Order descending chronologically._ 303 | 304 | * [Survey of existing cache implementations][1], by @dragoonis 305 | * [Strong vs. Weak informal poll][2], by @Crell 306 | * [Implementation details informal poll][3], by @Crell 307 | 308 | [1]: https://docs.google.com/spreadsheet/ccc?key=0Ak2JdGialLildEM2UjlOdnA4ekg3R1Bfeng5eGlZc1E#gid=0 309 | [2]: https://docs.google.com/spreadsheet/ccc?key=0AsMrMKNHL1uGdDdVd2llN1kxczZQejZaa3JHcXA3b0E#gid=0 310 | [3]: https://docs.google.com/spreadsheet/ccc?key=0AsMrMKNHL1uGdEE3SU8zclNtdTNobWxpZnFyR0llSXc#gid=1 311 | -------------------------------------------------------------------------------- /proposed/container.md: -------------------------------------------------------------------------------- 1 | Container interface 2 | =================== 3 | 4 | This document describes a common interface for dependency injection containers. 5 | 6 | The goal set by `ContainerInterface` is to standardize how frameworks and libraries make use of a 7 | container to obtain objects and parameters (called *entries* in the rest of this document). 8 | 9 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", 10 | "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be 11 | interpreted as described in [RFC 2119][]. 12 | 13 | The word `implementor` in this document is to be interpreted as someone 14 | implementing the `ContainerInterface` in a dependency injection-related library or framework. 15 | Users of dependency injections containers (DIC) are referred to as `user`. 16 | 17 | [RFC 2119]: http://tools.ietf.org/html/rfc2119 18 | 19 | 1. Specification 20 | ----------------- 21 | 22 | ### 1.1 Basics 23 | 24 | - The `Psr\Container\ContainerInterface` exposes two methods : `get` and `has`. 25 | 26 | - `get` takes one mandatory parameter: an entry identifier. It MUST be a string. 27 | A call to `get` can return anything (a *mixed* value), or throws an exception if the identifier 28 | is not known to the container. Two successive calls to `get` with the same 29 | identifier SHOULD return the same value. However, depending on the `implementor` 30 | design and/or `user` configuration, different values might be returned, so 31 | `user` SHOULD NOT rely on getting the same value on 2 successive calls. 32 | While `ContainerInterface` only defines one mandatory parameter in `get()`, implementations 33 | MAY accept additional optional parameters. 34 | 35 | - `has` takes one unique parameter: an entry identifier. It MUST return `true` 36 | if an entry identifier is known to the container and `false` if it is not. 37 | 38 | ### 1.2 Exceptions 39 | 40 | Exceptions directly thrown by the container MUST implement the 41 | [`Psr\Container\Exception\ContainerExceptionInterface`](#container-exception). 42 | 43 | A call to the `get` method with a non-existing id SHOULD throw a 44 | [`Psr\Container\Exception\NotFoundExceptionInterface`](#not-found-exception). 45 | 46 | ### 1.3 Additional feature: Delegate lookup 47 | 48 | This section describes an additional feature that MAY be added to a container. Containers are not 49 | required to implement the *delegate lookup* to respect the `ContainerInterface`. 50 | 51 | The goal of the *delegate lookup* feature is to allow several containers to share entries. 52 | Containers implementing this feature can perform dependency lookups in other containers. 53 | 54 | Containers implementing this feature will offer a greater lever of interoperability 55 | with other containers. Implementation of this feature is therefore RECOMMENDED. 56 | 57 | A container implementing this feature: 58 | 59 | - MUST implement the `ContainerInterface` 60 | - MUST provide a way to register a delegate container (using a constructor parameter, or a setter, 61 | or any possible way). The delegate container MUST implement the `ContainerInterface`. 62 | 63 | When a container is configured to use a delegate container for dependencies: 64 | 65 | - Calls to the `get` method should only return an entry if the entry is part of the container. 66 | If the entry is not part of the container, an exception should be thrown 67 | (as requested by the `ContainerInterface`). 68 | - Calls to the `has` method should only return `true` if the entry is part of the container. 69 | If the entry is not part of the container, `false` should be returned. 70 | - If the fetched entry has dependencies, **instead** of performing 71 | the dependency lookup in the container, the lookup is performed on the *delegate container*. 72 | 73 | Important! By default, the lookup SHOULD be performed on the delegate container **only**, not on the container itself. 74 | 75 | It is however allowed for containers to provide exception cases for special entries, and a way to lookup 76 | into the same container (or another container) instead of the delegate container. 77 | 78 | 2. Package 79 | ---------- 80 | 81 | The interfaces and classes described as well as relevant exception are provided as part of the 82 | [psr/container](https://packagist.org/packages/psr/container) package. (still to-be-created) 83 | 84 | 2. Interfaces 85 | ------------- 86 | 87 | 88 | ### 2.1. `Psr\Container\ContainerInterface` 89 | 90 | ```php 91 | 127 | ### 2.2. `Psr\Container\Exception\ContainerExceptionInterface` 128 | 129 | ```php 130 | 142 | ### 2.3. `Psr\Container\Exception\NotFoundExceptionInterface` 143 | 144 | ```php 145 | The intent of this guide is to reduce cognitive friction when scanning code from 43 | > different authors. It does so by enumerating a shared set of rules and expectations 44 | > about how to format PHP code. 45 | > When various authors collaborate across multiple projects, it helps to have one set 46 | > of guidelines to be used among all those projects. Thus, the benefit of this guide is 47 | > not in the rules themselves, but in the sharing of those rules. 48 | 49 | This PSR is an extension of PSR-2, and therefore also an extension of PSR-1. It shall be 50 | included in the document that compliance with PSR-N implicitly requires compliance with 51 | PSR-2 and PSR-1. 52 | 53 | This PSR will include coding style guidelines related to new functionality added to PHP 54 | after the publication of PSR-2; this includes PHP 5.5, PHP 5.6 and PHP 7.0. 55 | 56 | This PSR will also include clarifications on the text of PSR-2, as described in the 57 | PSR-2 Errata. 58 | 59 | ## 3.2 Non-Goals 60 | 61 | It is not the intention of this PSR to add entirely new coding style guidelines that 62 | were available to be considered for inclusion in PSR-1 or PSR-2. 63 | 64 | PSR-N will also not change anything stipulated in PSR-1 and PSR-2. 65 | 66 | 4. Approaches 67 | ------------- 68 | 69 | The overarching approach is to attempt to apply existing PSR-2 styling and rationale to 70 | new functionality as opposed to establishing new conventions. 71 | 72 | 73 | 5. People 74 | --------- 75 | 76 | ### 5.1 Editor(s) 77 | 78 | * Michael Cullum 79 | 80 | ### 5.2 Sponsors 81 | 82 | * Korvin Szanto - concrete5 (Coordinator) 83 | * Alexander Makarov - Yii Framework 84 | 85 | 6. Votes 86 | -------- 87 | 88 | * **Entrance Vote: ** https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!msg/php-fig/P9atZLOcUBM/_jwkvlYKEAAJ 89 | 90 | 7. Relevant Links 91 | ----------------- 92 | 93 | _**Note:** Order descending chronologically._ 94 | 95 | * [Inspiration Mailing List Thread](https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!topic/php-fig/wh9avopSR9k) 96 | * [Initial Mailing List PSR Proposal Thread](https://groups.google.com/forum/?utm_medium=email&utm_source=footer#!topic/php-fig/MkFacLdfGso) 97 | -------------------------------------------------------------------------------- /proposed/images/interoperating_containers.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/async-interop/fig-standards/de32aeb2e1c6e942dc3064c4c31c747877fb1114/proposed/images/interoperating_containers.png -------------------------------------------------------------------------------- /proposed/images/priority.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/async-interop/fig-standards/de32aeb2e1c6e942dc3064c4c31c747877fb1114/proposed/images/priority.png -------------------------------------------------------------------------------- /proposed/images/side_by_side_containers.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/async-interop/fig-standards/de32aeb2e1c6e942dc3064c4c31c747877fb1114/proposed/images/side_by_side_containers.png -------------------------------------------------------------------------------- /proposed/psr-8-hug/PSR-8-hug-meta.md: -------------------------------------------------------------------------------- 1 | PSR-8 Meta Document 2 | =================== 3 | 4 | 1. Summary 5 | ---------- 6 | 7 | The intent of this spec is to improve the overall amicability and cooperative 8 | spirit of the PHP community through a standardized means of inter-project 9 | affection and support. 10 | 11 | 2. Votes 12 | -------- 13 | 14 | - **Entrance Vote:** 15 | - **Acceptance Vote:** 16 | 17 | 18 | 3. Errata 19 | --------- 20 | 21 | 22 | 23 | 4. People 24 | --------- 25 | 26 | ### 5.1 Editor 27 | 28 | - Larry Garfield, Drupal 29 | 30 | ### 5.2 Sponsors 31 | 32 | - Cal Evans, the PHP Community (Coordinator) 33 | - Paul Jones, Aura 34 | -------------------------------------------------------------------------------- /proposed/psr-8-hug/psr-8-hug.md: -------------------------------------------------------------------------------- 1 | Mutually Assured Hug 2 | ==================== 3 | 4 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", 5 | "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be 6 | interpreted as described in [RFC 2119](http://tools.ietf.org/html/rfc2119). 7 | 8 | 9 | ## 1. Overview 10 | 11 | This standard establishes a common way for objects to express mutual 12 | appreciation and support by hugging. This allows objects to support each other 13 | in a constructive fashion, furthering cooperation between different PHP projects. 14 | 15 | ## 2. Specification 16 | 17 | This specification defines two interfaces, \Psr\Hug\Huggable and 18 | \Psr\Hug\GroupHuggable. 19 | 20 | ### Huggable objects 21 | 22 | 1. A Huggable object expresses affection and support for another object by invoking 23 | its hug() method, passing $this as the first parameter. 24 | 25 | 2. An object whose hug() method is invoked MUST hug() the calling object back 26 | at least once. 27 | 28 | 3. Two objects that are engaged in a hug MAY continue to hug each other back for 29 | any number of iterations. However, every huggable object MUST have a termination 30 | condition that will prevent an infinite loop. For example, an object MAY be 31 | configured to only allow up to 3 mutual hugs, after which it will break the hug 32 | chain and return. 33 | 34 | 4. An object MAY take additional actions, including modifying state, when hugged. 35 | A common example is to increment an internal happiness or satisfaction counter. 36 | 37 | ### GroupHuggable objects 38 | 39 | 1. An object may optionally implement GroupHuggable to indicate that it is able 40 | to support and affirm multiple objects at once. 41 | 42 | 43 | ## 3. Interfaces 44 | 45 | ### HuggableInterface 46 | 47 | ````php 48 | namespace Psr\Hug; 49 | 50 | /** 51 | * Defines a huggable object. 52 | * 53 | * A huggable object expresses mutual affection with another huggable object. 54 | */ 55 | interface Huggable 56 | { 57 | 58 | /** 59 | * Hugs this object. 60 | * 61 | * All hugs are mutual. An object that is hugged MUST in turn hug the other 62 | * object back by calling hug() on the first parameter. All objects MUST 63 | * implement a mechanism to prevent an infinite loop of hugging. 64 | * 65 | * @param Huggable $h 66 | * The object that is hugging this object. 67 | */ 68 | public function hug(Huggable $h); 69 | } 70 | ```` 71 | 72 | ````php 73 | namespace Psr\Hug; 74 | 75 | /** 76 | * Defines a huggable object. 77 | * 78 | * A huggable object expresses mutual affection with another huggable object. 79 | */ 80 | interface GroupHuggable extends Huggable 81 | { 82 | 83 | /** 84 | * Hugs a series of huggable objects. 85 | * 86 | * When called, this object MUST invoke the hug() method of every object 87 | * provided. The order of the collection is not significant, and this object 88 | * MAY hug each of the objects in any order provided that all are hugged. 89 | * 90 | * @param $huggables 91 | * An array or iterator of objects implementing the Huggable interface. 92 | */ 93 | public function groupHug($huggables); 94 | } 95 | ```` 96 | 97 | -------------------------------------------------------------------------------- /proposed/security-disclosure-publication-meta.md: -------------------------------------------------------------------------------- 1 | Security Disclosure Meta Document 2 | ================================= 3 | 4 | 1. Summary 5 | ---------- 6 | 7 | There are two aspects with dealing with security issues: One is the process 8 | by which security issues are reported and fixed in projects, the other 9 | is how the general public is informed about the issues and any remedies 10 | available. While PSR-9 addresses the former, this PSR, ie. PSR-10, deals with 11 | the later. So the goal of PSR-10 is to define how security issues are disclosed 12 | to the public and what format such disclosures should follow. Especially today 13 | where PHP developers are sharing code across projects more than ever, this PSR 14 | aims to ease the challenges in keeping an overview of security issues in all 15 | dependencies and the steps required to address them. 16 | 17 | 2. Why Bother? 18 | -------------- 19 | 20 | End users want to ensure that they stay informed about security issues. 21 | However they also want to be able to quickly check if they are affected to be 22 | able to take the necessary steps. 23 | 24 | Upstream users of code will also want to know these details. Furthermore they 25 | will want to know if its possible for them to be included into possible closed 26 | discussions before details about a security issue are made public. 27 | 28 | 3. Scope 29 | -------- 30 | 31 | ## 3.1 Goals 32 | 33 | * Means to help in (semi-)automating discovery and fixing of known security 34 | issues in projects using the affected code 35 | 36 | ## 3.2 Non-Goals 37 | 38 | * Process for how vulnerabilities are reported and fixed 39 | * Methods for reducing security vulnerabilities 40 | 41 | 4. Approaches 42 | ------------- 43 | 44 | A key aspect here is that the information flow should be as structured as 45 | possible to enable as much automation as possible. For example, 46 | vulnerabilities should be published in a defined location and in a defined 47 | format. Inspiration could be taken from [1]. 48 | 49 | That being said, the standard should not rely on any central authority 50 | above the projects. This is to ensure that no project becomes depend on an 51 | outside authority for something as sensitive as security related topics. 52 | However due to defined locations and formats, it will become possible for 53 | other people to build centralized tools around this information. 54 | 55 | 5. People 56 | --------- 57 | 58 | ### 5.1 Editor 59 | 60 | * Lukas Kahwe Smith 61 | 62 | ### 5.2 Sponsors 63 | 64 | * Larry Garfield (Drupal) 65 | * Korvin Szanto (concrete5) 66 | 67 | ### 5.3 Coordinator 68 | 69 | * Korvin Szanto (concrete5) 70 | 71 | 6. Votes 72 | -------- 73 | 74 | 75 | 7. Relevant Links 76 | ----------------- 77 | 78 | [1]: https://github.com/FriendsOfPHP/security-advisories 79 | 80 | Initial discussion: https://groups.google.com/d/msg/php-fig/45AIj5bPHJ4/ThERB43j-u8J 81 | Discussion: https://groups.google.com/forum/#!forum/php-fig-psr-9-discussion 82 | -------------------------------------------------------------------------------- /proposed/security-disclosure-publication.md: -------------------------------------------------------------------------------- 1 | ## Introduction 2 | 3 | There are two aspects with dealing with security issues: One is the process 4 | by which security issues are reported and fixed in projects, the other 5 | is how the general public is informed about the issues and any remedies 6 | available. While PSR-9 addresses the former, this PSR, ie. PSR-10, deals with 7 | the later. So the goal of PSR-10 is to define how security issues are disclosed 8 | to the public and what format such disclosures should follow. Especially today 9 | where PHP developers are sharing code across projects more than ever, this PSR 10 | aims to ease the challenges in keeping an overview of security issues in all 11 | dependencies and the steps required to address them. 12 | 13 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", 14 | "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be 15 | interpreted as described in [RFC 2119][]. 16 | 17 | [RFC 2119]: http://tools.ietf.org/html/rfc2119 18 | 19 | ## Goal 20 | 21 | The goal of this PSR is to give project leads a clearly defined approach 22 | to enabling end users to discover security disclosures using a clearly 23 | defined structured format for these disclosures. 24 | 25 | ## Disclosure Discovery 26 | 27 | Every project MUST provide a link to its security vulnerability database in 28 | an obvious place. Ideally this should be on the root page of the main domain of the given 29 | project. This MAY be a sub-domain in case it is a sub-project of a larger 30 | initiative. If the project has a dedicated page for its disclosure process 31 | discovery then this is also considered a good place for this link. 32 | The link MAY use the custom link relation ``php-vuln-disclosures``, 33 | ie. for example 34 | ````. 35 | 36 | Note that projects MAY choose to host their disclosure files on a domain 37 | other than their main project page. It is RECOMMENDED to not store the 38 | disclosures in a VCS as this can lead to the confusions about which branch 39 | is the relevant branch. If a VCS is used then additional steps SHOULD be taken 40 | to clearly document to users which branch contains all vulnerabilities for 41 | all versions. If necessary projects MAY however split vulnerability disclosure 42 | files by major version number. In this case again this SHOULD be clearly 43 | documented. 44 | 45 | ## Disclosure Format 46 | 47 | The disclosure format is based on Atom [1], which in turn is based on XML. It 48 | leverages the "The Common Vulnerability Reporting Framework (CVRF) v1.1" [2]. 49 | Specifically it leverages its dictionary [3] as its base terminology. 50 | 51 | **TODO**: Should we also provide a JSON serialization to lower the bar for projects. 52 | Aggregation services can then spring up to provide an Atom representation of 53 | these disclosures in JSON format. 54 | 55 | The Atom extensions [4] allow a structured description of the vulnerability to 56 | enable automated tools to determine if installed is likely affected by the 57 | vulnerability. However human readability is considered highly important and as 58 | such not the full CVRF is used. 59 | 60 | **TODO**: Review the Atom format and the supplied XSD 61 | 62 | Note that for each vulnerability only a single entry MUST be created. In case 63 | any information changes the original file MUST be updated along with the last 64 | update field. 65 | 66 | Any disclosure uses ``entryType`` using the following tags from the Atom 67 | namespace (required tags are labeled with "MUST"): 68 | 69 | * title (short description of the vulnerability and affected versions, MUST) 70 | * summary (description of the vulnerability) 71 | * author (contact information, MUST) 72 | * published (initial publication date, MUST) 73 | * updated (date of the last update) 74 | * link (to reference more information) 75 | * id (project specific vulnerability id) 76 | 77 | In addition the following tags are added: 78 | 79 | * reported (initial report date) 80 | * reportedBy (contact information for the persons or entity that initially reported the vulnerability) 81 | * resolvedBy (contact information for the persons or entity that resolved the vulnerability) 82 | * name (name of the product, MUST) 83 | * cve (unique CVE ID) 84 | * cwe (unique CWE ID) 85 | * severity (low, medium high) 86 | * affected (version(s) using composer syntax [5]) 87 | * status (open, in progress, disputed, completed, MUST) 88 | * remediation (textual description for how to fix an affected system) 89 | * remediationType (workaround, mitigation, vendor fix, none available, will not fix) 90 | * remediationLink (URL to give additional information for remediation) 91 | 92 | [1] https://tools.ietf.org/html/rfc4287 93 | [2] http://www.icasi.org/cvrf-1.1 94 | [3] http://www.icasi.org/cvrf-1.1-dictionary 95 | [4] security-disclosure-publication.xsd 96 | [5] https://getcomposer.org/doc/01-basic-usage.md#package-versions 97 | -------------------------------------------------------------------------------- /proposed/security-disclosure-publication.xsd: -------------------------------------------------------------------------------- 1 | 2 | 3 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | The PHP FIG security disclosure remediation construct is to be used to specify a specific remediation 45 | option for a specific vulnerability. 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | -------------------------------------------------------------------------------- /proposed/security-reporting-process-meta.md: -------------------------------------------------------------------------------- 1 | Security Disclosure Meta Document 2 | ================================= 3 | 4 | 1. Summary 5 | ---------- 6 | 7 | There are two aspects with dealing with security issues: One is the process 8 | by which security issues are reported and fixed in projects, the other 9 | is how the general public is informed about the issues and any remedies 10 | available. While PSR-10 addresses the later, this PSR, ie. PSR-9, deals with 11 | the former. So the goal of PSR-9 is to define the process by which security 12 | researchers and report security vulnerabilities to projects. It is important 13 | that when security vulnerabilities are found that researchers have an easy 14 | channel to the projects in question allowing them to disclose the issue to a 15 | controlled group of people. 16 | 17 | 2. Why Bother? 18 | -------------- 19 | 20 | As of right now, there isn't a common standard for most parts of this process. 21 | That is there isn't a standard where researchers can find out about the 22 | process for handling security issues for any given project. There is also 23 | no standard that explains to researchers what they can expect to happen if 24 | they report a vulnerability. More importantly there is no standard on which 25 | projects can base the security reporting process that best fits them. 26 | 27 | 3. Scope 28 | -------- 29 | 30 | ## 3.1 Goals 31 | 32 | * A defined process for how vulnerabilities are reported, the process by which 33 | these get fixed and finally disclosed to the public 34 | 35 | ## 3.2 Non-Goals 36 | 37 | * Methods for reducing security vulnerabilities 38 | * Publication of security issues and fixes (see PSR-10) 39 | 40 | 4. Approaches 41 | ------------- 42 | 43 | Currently the most viable approach seems to be defining a base line workflow 44 | for how security vulnerabilities go from discovery to fixing to public 45 | disclosure. Inspiration could be drawn from this list of security disclosure 46 | processes in various PHP and non-PHP projects: 47 | 48 | * http://symfony.com/doc/current/contributing/code/security.html 49 | * http://framework.zend.com/security/ 50 | * http://www.yiiframework.com/security/ 51 | * https://www.drupal.org/security 52 | * http://codex.wordpress.org/FAQ_Security 53 | * http://www.sugarcrm.com/page/sugarcrm-security-policy/en 54 | * http://typo3.org/teams/security/ 55 | * http://cakephp.org/development 56 | * http://www.concrete5.org/developers/security/ 57 | * http://developer.joomla.org/security.html 58 | * http://wiki.horde.org/SecurityManagement 59 | * http://www.revive-adserver.com/support/bugs/ 60 | * http://magento.com/security 61 | * http://www.apache.org/security/committers.html 62 | * https://www.mozilla.org/en-US/about/governance/policies/security-group/bugs/ 63 | * http://www.openbsd.org/security.html 64 | 65 | A summary of the differences and similarities can be found here: 66 | https://groups.google.com/d/msg/php-fig-psr-9-discussion/puGV_X0bj_M/Jr_IAS40StsJ 67 | 68 | 5. People 69 | --------- 70 | 71 | ### 5.1 Editor 72 | 73 | * Lukas Kahwe Smith 74 | 75 | ### 5.2 Sponsors 76 | 77 | * Larry Garfield (Drupal) 78 | * Korvin Szanto (concrete5) 79 | 80 | ### 5.3 Coordinator 81 | 82 | * Korvin Szanto (concrete5) 83 | 84 | 6. Votes 85 | -------- 86 | 87 | 88 | 7. Relevant Links 89 | ----------------- 90 | 91 | [1]: http://symfony.com/doc/current/contributing/code/security.html -------------------------------------------------------------------------------- /proposed/security-reporting-process.md: -------------------------------------------------------------------------------- 1 | ## Introduction 2 | 3 | There are two aspects with dealing with security issues: One is the process 4 | by which security issues are reported and fixed in projects, the other 5 | is how the general public is informed about the issues and any remedies 6 | available. While PSR-10 addresses the later, this PSR, ie. PSR-9, deals with 7 | the former. So the goal of PSR-9 is to define the process by which security 8 | researchers and report security vulnerabilities to projects. It is important 9 | that when security vulnerabilities are found that researchers have an easy 10 | channel to the projects in question allowing them to disclose the issue to a 11 | controlled group of people. 12 | 13 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", 14 | "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be 15 | interpreted as described in [RFC 2119][]. 16 | 17 | [RFC 2119]: http://tools.ietf.org/html/rfc2119 18 | 19 | ## Goal 20 | 21 | The goal of this PSR is to give researchers, project leads, upstream project 22 | leads and end users a defined and structured process for disclosing security 23 | vulnerabilities. 24 | 25 | ## Security Disclosure Process Discovery 26 | 27 | Every project MUST provide a link to its security disclosure process in 28 | an obvious place. Ideally this should be on the root page the main domain of 29 | the given project. This MAY be a sub-domain in case it is a sub-project of a 30 | larger initiative. The link MAY use the custom link relation 31 | ``php-vuln-reporting``, ie. for example 32 | ````. 33 | 34 | Projects SHOULD ideally make the location prominent itself 35 | by either creating a dedicated sub-domain like ``http://security.example.org`` 36 | or by making it a top level directory like ``http://example.org/security``. 37 | Alternatively projects MAY also simply reference this document, ie. PSR-9. 38 | By referencing PSR-9 a project basically states that they follow the 39 | default procedures as noted in the section "Default Procedures" towards 40 | the end of this document. Projects MUST list the variables noted at the start 41 | of that section in this reference (ie. project name, project domain, etc.). 42 | Projects MAY choose to list any part of the procedures that is not a MUST 43 | which they choose to omit. 44 | 45 | Note that projects MAY not have a dedicated domain. For example a project 46 | hosted on Github, Bitbucket or other service should still ensure that the 47 | process is referenced on the landing page, ie. for example 48 | http://github.com/example/somelib should ensure that the default branch 49 | has a README file which references the procedures used so that it is 50 | automatically displayed. 51 | 52 | If necessary projects MAY have different disclosure process 53 | for different major version number. In this case one URL MUST be provided 54 | for each major version. In the case a major version is no longer receiving 55 | security fixes, instead of an URL a project MAY opt to instead simply 56 | note that the version is no longer receiving security fixes. 57 | 58 | ## Security Disclosure Process 59 | 60 | Every project MUST provide an email address in their security disclosure 61 | process description as the ``contact email address``. Projects SHALL NOT 62 | use contact forms. 63 | 64 | **TODO**: Add more things found here https://groups.google.com/d/msg/php-fig-psr-9-discussion/puGV_X0bj_M/Jr_IAS40StsJ? 65 | 66 | ## Default Procedures 67 | 68 | * ``[project name]`` denotes the name on which the project uses to identify itself. 69 | * ``[project domain]`` denotes the main (sub)domain on which the project relies. 70 | 71 | If not specified otherwise, the ``contact email address`` is ``security@[project domain]``. 72 | 73 | **TODO**: Add more things noted in the previous section --------------------------------------------------------------------------------