Lecture
`\Symfony\Core\Request` => `/path/to/project/lib/vendor/Symfony/Core/Request.php`
`\Zend\Acl` => `/path/to/project/lib/vendor/Zend/Acl.php`
`\namespace\package_name\Class_Name` => `/path/to/project/lib/vendor/namespace/package_name/Class/Name.php`
<?php
namespace Vendor\Package;
use FooInterface;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;
class Foo extends Bar implements FooInterface
{
public function sampleFunction($a, $b = null)
{
if ($a === $b) {
bar();
} elseif ($a > $b) {
$foo->bar($arg1);
} else {
BazClass::bar($arg2, $arg3);
}
}
final public static function bar()
{
// method body
}
}
This document describes a common interface for logging libraries.
It is a simple and universal way. SHOULD remain compatible with this document. This will ensure that you can use the centralized application logs.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
It is interpreted to be interpreted in a document-related library or framework. Users of loggers are referred to as user .
RFC 5424 levels (debug, info, notice, warning, error, critical, alert, emergency).
A ninth method, log , accepts a log level as first argument. Constants MUST have the same result. MUST throw a Psr\Log\InvalidArgumentException . SHOULD you use it.
Every method accepts a string with a __toString() method. Implementors MAY have special handling for the passed objects. If it is not the case, implementors MUST cast it to a string.
The message MAY contains placeholders which replace the values from the context array.
Placeholder names MUST correspond to keys in the context array.
Placeholder names MUST be delimited with a single opening brace. There must not be any whitespace between the delimiters and the placeholder name.
Placeholder names SHOULD be composed only of the characters AZ , az , 0-9 , underscore _ , and period . . It is reserved.
Implementors MAY use placeholders to implement various escaping strategies and translate logs for display. SHOULD NOT pre-escape placeholder values since the data will be displayed.
The following is an example of implementation of placeholder interpolation provided for reference purposes:
/ **
* Interpolates context values into the message placeholders.
* /
function interpolate ($ message, array $ context = array ())
{
// build a replacement array with braces around the context keys
$ replace = array ();
foreach ($ context as $ key => $ val) {
$ replace ['{'. $ key. '}'] = $ val;
}
// interpolate replacement values into the message and return
return strtr ($ message, $ replace);
}
// a message with brace-delimited placeholder names
$ message = "User {username} created";
// a context array of placeholder names => replacement values
$ context = array ('username' => 'bolivar');
// echoes "User bolivar created"
echo interpolate ($ message, $ context); Every method accepts an array as context data. This is not a very well-defined information. The array can contain anything. Implementors MUST ensure that it is possible. Must have a note of interest, a warning or warning.
MUST be in the 'exception' key. For example, it supports the logging exceptions. Implementors MUST still verify that the MAY contain anything.
The Psr\Log\AbstractLogger class allows you to easily implement the LoggerInterface . Context of it.
Similarly, using the Psr\Log\LoggerTrait the generic log method. Note that since you can not implement interfaces, LoggerInterface .
The Psr\Log\NullLogger is provided together with the interface. It’s possible to use it. However, the context data creation is expensive.
The Psr\Log\LoggerAwareInterface only contains a setLogger(LoggerInterface $logger) .
The Psr\Log\LoggerAwareTrait trait can be used to implement it. It gives you access to $this->logger .
The Psr\Log\LogLevel class holds the eight log levels.
This is the case in the psr / log package.
Psr\Log\LoggerInterface <? php
namespace Psr \ Log;
/ **
* Describes a logger instance
*
* The message MUST be a string or object implementing __toString ().
*
* The message MAY contain placeholders in the form: {foo} where foo
* will be replaced by the context data in key "foo".
*
* The context array can be arbitrary data assumption that
* Except instance is given.
* to produce a stack trace, it must be in a key named "exception".
*
* See https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md
* for the full interface specification.
* /
interface LoggerInterface
{
/ **
* System is unusable.
*
* @param string $ message
* @param array $ context
* @return null
* /
public function emergency ($ message, array $ context = array ());
/ **
* Action must be taken immediately.
*
* Example: Entire website down, database unavailable, etc. This should
* trigger SMS alerts and wake you up.
*
* @param string $ message
* @param array $ context
* @return null
* /
public function alert ($ message, array $ context = array ());
/ **
* Critical conditions.
*
* Example: Application component unavailable, unexpected exception.
*
* @param string $ message
* @param array $ context
* @return null
* /
public function critical ($ message, array $ context = array ());
/ **
* Runtime errors typically
* be logged and monitored.
*
* @param string $ message
* @param array $ context
* @return null
* /
public function error ($ message, array $ context = array ());
/ **
* Exceptional occurrences that are not errors.
*
* Example: use of deprecated APIs, poor use of an API, undesirable things
* that are not necessarily wrong.
*
* @param string $ message
* @param array $ context
* @return null
* /
public function warning ($ message, array $ context = array ());
/ **
* Normal but significant events.
*
* @param string $ message
* @param array $ context
* @return null
* /
public function notice ($ message, array $ context = array ());
/ **
* Interesting events.
*
* Example: User logs in, SQL logs.
*
* @param string $ message
* @param array $ context
* @return null
* /
public function info ($ message, array $ context = array ());
/ **
* Detailed debug information.
*
* @param string $ message
* @param array $ context
* @return null
* /
public function debug ($ message, array $ context = array ());
/ **
* Logs with an arbitrary level.
*
* @param mixed $ level
* @param string $ message
* @param array $ context
* @return null
* /
public function log ($ level, $ message, array $ context = array ());
} Psr\Log\LoggerAwareInterface <? php
namespace Psr \ Log;
/ **
* Describes a logger-aware instance
* /
interface LoggerAwareInterface
{
/ **
* Sets a logger instance on the object
*
* @param LoggerInterface $ logger
* @return null
* /
public function setLogger (LoggerInterface $ logger);
} Psr\Log\LogLevel <? php
namespace Psr \ Log;
/ **
* Describes log levels
* /
class LogLevel
{
const EMERGENCY = 'emergency';
const ALERT = 'alert';
const CRITICAL = 'critical';
const ERROR = 'error';
const WARNING = 'warning';
const NOTICE = 'notice';
const INFO = 'info';
const DEBUG = 'debug';
}
The following are examples illustrate PSR-4 compliant code:
<? php
/ **
* An example of a project-specific implementation.
*
* After registering this autoload function with SPL, the following line
* Foo \ Bar \ Baz \ Qux class
* from /path/to/project/src/Baz/Qux.php:
*
* new \ Foo \ Bar \ Baz \ Qux;
*
* @param string $ class The fully-qualified class name.
* @return void
* /
spl_autoload_register (function ($ class) {
// project-specific namespace prefix
$ prefix = 'Foo \\ Bar \\';
// base directory for the namespace prefix
$ base_dir = __DIR__. '/ src /';
// does the class use the namespace prefix?
$ len = strlen ($ prefix);
if (strncmp ($ prefix, $ class, $ len)! == 0) {
// no, move to the next registered autoloader
return;
}
// get the relative class name
$ relative_class = substr ($ class, $ len);
// replace the namespace prefix with the base directory, replace namespace
// separators with directory, directory, append
// with .php
$ file = $ base_dir. str_replace ('\\', '/', $ relative_class). '.php';
// if the file exists, require it
if (file_exists ($ file)) {
require $ file;
}
}); The following is an example of multiple class namespaces:
<? php
namespace Example;
/ **
* An example of a general-purpose implementation that includes the optional
* functionality of the multiple namespace
* prefix.
*
* Given the foo-bar package at the following
* paths ...
*
* / path / to / packages / foo-bar /
* src /
* Baz.php # Foo \ Bar \ Baz
* Qux /
* Quux.php # Foo \ Bar \ Qux \ Quux
* tests /
* BazTest.php # Foo \ Bar \ BazTest
* Qux /
* QuuxTest.php # Foo \ Bar \ Qux \ QuuxTest
*
* ... add the prefix files to the \ Foo \ Bar \ namespace
* as follows:
*
* <? php
* // instantiate the loader
* $ loader = new \ Example \ Psr4AutoloaderClass;
*
* // register the autoloader
* $ loader-> register ();
*
* // register the base directories for the namespace prefix
* $ loader-> addNamespace ('Foo \ Bar', '/ path / to / packages / foo-bar / src');
* $ loader-> addNamespace ('Foo \ Bar', '/ path / to / packages / foo-bar / tests');
*
The following line would have been
* \ Foo \ Bar \ Qux \ Quux class from /path/to/packages/foo-bar/src/Qux/Quux.php:
*
* <? php
* new \ Foo \ Bar \ Qux \ Quux;
*
The following line would have been
* \ Foo \ Bar \ Qux \ QuuxTest class from /path/to/packages/foo-bar/tests/Qux/QuuxTest.php:
*
* <? php
* new \ Foo \ Bar \ Qux \ QuuxTest;
* /
class Psr4AutoloaderClass
{
/ **
* An associative array where the key is a namespace prefix and the value
* is an array of base directories for classes in that namespace.
*
* @var array
* /
protected $ prefixes = array ();
/ **
* Register loader with SPL autoloader stack.
*
* @return void
* /
public function register ()
{
spl_autoload_register (array ($ this, 'loadClass'));
}
/ **
* Adds a base directory for a namespace prefix.
*
* @param string $ prefix The namespace prefix.
* @param string $ base_dir A base directory for class files in
* namespace.
* @param bool prepend If true, prepend the base directory to the stack
* instead of appending it; first cause
* than last.
* @return void
* /
public function addNamespace ($ prefix, $ base_dir, $ prepend = false)
{
// normalize namespace prefix
$ prefix = trim ($ prefix, '\\'). '\\';
// normalize the base directory with a trailing separator
$ base_dir = rtrim ($ base_dir, DIRECTORY_SEPARATOR). '/';
// initialize the namespace prefix array
if (isset ($ this-> prefixes [$ prefix]) === false) {
$ this-> prefixes [$ prefix] = array ();
}
// retain the base directory for the namespace prefix
if ($ prepend) {
array_unshift ($ this-> prefixes [$ prefix], $ base_dir);
} else {
array_push ($ this-> prefixes [$ prefix], $ base_dir);
}
}
/ **
* Loads the class file for a given class name.
*
* @param string $ class The fully-qualified class name.
* @return mixed
* failure.
* /
public function loadClass ($ class)
{
// the current namespace prefix
$ prefix = $ class;
// work backwards through the namesspace of the fully-qualified
// class name to find a mapped file name
while (false! == $ pos = strrpos ($ prefix, '\\')) {
// retain the trailing namespace separator in the prefix
$ prefix = substr ($ class, 0, $ pos + 1);
// the rest is the relative class name
$ relative_class = substr ($ class, $ pos + 1);
// try to load a mapped file for the prefix and relative class
$ mapped_file = $ this-> loadMappedFile ($ prefix, $ relative_class);
if ($ mapped_file) {
return $ mapped_file;
}
// remove the trailing namespace separator for the next iteration
// of strrpos ()
$ prefix = rtrim ($ prefix, '\\');
}
// never found a mapped file
return false;
}
/ **
* Load the mapped file for a namespace prefix and relative class.
*
* @param string $ prefix The namespace prefix.
* @param string $ relative_class The relative class name.
* @return mixed Boolean if no mapped file can be loaded, or the
* name of the mapped file that was loaded.
* /
protected function loadMappedFile ($ prefix, $ relative_class)
{
// are there any base directories for this namespace prefix?
if (isset ($ this-> prefixes [$ prefix]) === false) {
return false;
}
// look through base directories for this namespace prefix
foreach ($ this-> prefixes [$ prefix] as $ base_dir) {
// replace the namespace prefix with the base directory,
// replace namespace separators with directory separators
// in the relative class name, append with .php
$ file = $ base_dir
. str_replace ('\\', '/', $ relative_class)
. '.php';
// if the mapped file exists, require it
if ($ this-> requireFile ($ file)) {
// yes, we're done
return $ file;
}
}
// never found it
return false;
}
/ **
* If a file exists, require it from the file system.
*
* @param string $ file The file to require.
* @return bool True if the file exists, false if not.
* /
protected function requireFile ($ file)
{
if (file_exists ($ file)) {
require $ file;
return true;
}
return false;
}
} The following example is one way of loader:
<? php
namespace Example \ Tests;
class MockPsr4AutoloaderClass extends Psr4AutoloaderClass
{
protected $ files = array ();
public function setFiles (array $ files)
{
$ this-> files = $ files;
}
protected function requireFile ($ file)
{
return in_array ($ file, $ this-> files);
}
}
class Psr4AutoloaderClassTest extends \ PHPUnit_Framework_TestCase
{
protected $ loader;
protected function setUp ()
{
$ this-> loader = new MockPsr4AutoloaderClass;
$ this-> loader-> setFiles (array (
'/vendor/foo.bar/src/ClassName.php',
'/vendor/foo.bar/src/DoomClassName.php',
'/vendor/foo.bar/tests/ClassNameTest.php',
'/vendor/foo.bardoom/src/ClassName.php',
'/vendor/foo.bar.baz.dib/src/ClassName.php',
'/vendor/foo.bar.baz.dib.zim.gir/src/ClassName.php',
))
$ this-> loader-> addNamespace (
'Foo \ bar',
'/vendor/foo.bar/src'
);
$ this-> loader-> addNamespace (
'Foo \ bar',
'/vendor/foo.bar/tests'
);
$ this-> loader-> addNamespace (
'Foo \ BarDoom',
'/vendor/foo.bardoom/src'
);
$ this-> loader-> addNamespace (
'Foo \ Bar \ Baz \ Dib',
'/vendor/foo.bar.baz.dib/src'
);
$ this-> loader-> addNamespace (
'Foo \ Bar \ Baz \ Dib \ Zim \ Gir',
'/vendor/foo.bar.baz.dib.zim.gir/src'
);
}
public function testExistingFile ()
{
$ actual = $ this-> loader-> loadClass ('Foo \ Bar \ ClassName');
$ expect = '/vendor/foo.bar/src/ClassName.php';
$ this-> assertSame ($ expect, $ actual);
$ actual = $ this-> loader-> loadClass ('Foo \ Bar \ ClassNameTest');
$ expect = '/vendor/foo.bar/tests/ClassNameTest.php';
$ this-> assertSame ($ expect, $ actual);
}
public function testMissingFile ()
{
$ actual = $ this-> loader-> loadClass ('No_Vendor \ No_Package \ NoClass');
$ this-> assertFalse ($ actual);
}
public function testDeepFile ()
{
$ actual = $ this-> loader-> loadClass ('Foo \ Bar \ Baz \ Dib \ Zim \ Gir \ ClassName');
$ expect = '/vendor/foo.bar.baz.dib.zim.gir/src/ClassName.php';
$ this-> assertSame ($ expect, $ actual);
}
public function testConfusion ()
{
$ actual = $ this-> loader-> loadClass ('Foo \ Bar \ DoomClassName');
$ expect = '/vendor/foo.bar/src/DoomClassName.php';
$ this-> assertSame ($ expect, $ actual);
$ actual = $ this-> loader-> loadClass ('Foo \ BarDoom \ ClassName');
$ expect = '/vendor/foo.bardoom/src/ClassName.php';
$ this-> assertSame ($ expect, $ actual);
}
}
Autoloader php registered autoloader. This would be an addition to, not a replacement for, PSR-0.
The PSR-0 convention is under the limitation of php 5.2 and previous. If you want to go to your pseudo-namespaces, like this:
/path/to/src/ VendorFoo/ Bar/ Baz.php # VendorFoo_Bar_Baz VendorDib/ Zim/ Gir.php # Vendor_Dib_Zim_Gir It was a rule that the phrases were released under the name of a new namespace notation. Underscores were encouraged to accept wider adoption.
/path/to/src/ VendorFoo/ Bar/ Baz.php # VendorFoo_Bar_Baz VendorDib/ Zim/ Gir.php # VendorDib_Zim_Gir Irk_Operation/ Impending_Doom/ V1.php V2.php # Irk_Operation\Impending_Doom\V2 If you are a installer, you must be able to get the installer back into the single central directory.
With Composer, package sources are no longer copied to a single global location. They are not used around. Comparser for PHP sources as with PEAR. Instead, there are multiple directories; each package is a separate directory for each project.
To meet the requirements of the PSR-0, this leads to Composer packages looking like this:
vendor/ vendor_name/ package_name/ src/ Vendor_Name/ Package_Name/ ClassName.php # Vendor_Name\Package_Name\ClassName tests/ Vendor_Name/ Package_Name/ ClassNameTest.php # Vendor_Name\Package_Name\ClassNameTest The "src" and "tests" directories have the directory names and package directory names. This is an artifact of PSR-0 compliance.
Deeper and more-repetitive than necessary. This proposal suggests that it would be useful to
vendor/ vendor_name/ package_name/ src/ ClassName.php # Vendor_Name\Package_Name\ClassName tests/ ClassNameTest.php # Vendor_Name\Package_Name\ClassNameTest "Package-oriented autoloading" (as vs the traditional "direct class-to-file autoloading").
It is difficult to implement an agreement or amendment to the PSR-0, because the PSR-0 doesn’t need it. This would be more complicated than the PSR-0. However, it would allow for cleaner packages.
Initially, the following rules were suggested:
Implementors MUST use at least two namespace levels: (This is a combination of the two-name combination of the name and the package namespace.)
Implementors MUST BE FUNDS:
MAY map to any directory. The remaining portion of the number is the identity portion of the number of identically-defined names.
Note that this is the end of the underscore-as-directory-separator in the class name. It would be possible to note that it would be a rule.
Retain the PSR-0 rule that you need to use at least two namespace levels:
Allow a path infix between the fully qualified class name.
Allow the package directory namespace.
End directory
Non-class resources
This eliminates the deeper directory structure. In addition, it specifies more specific rules that make implementations explicitly more interoperable.
Although autoloaders should handle errors. Specifically, it forbids throwing exceptions or raising errors. The reason is two-fold.
Autoloaders in PHP are explicitly designed to be stackable so that if you can’t get it, it’s not possible. Having an autoloader condition violates that compatibility.
class_exists() and interface_exists() allow "not found, even after trying to autoload" as a legitimate, normal use case. An autoloader that throws exceptions renders class_exists() unusable, which is completely unacceptable from an interoperability standpoint. It is not necessary to ensure that there is a need for a log of information.
Pros:
Shallower directory structures
More flexible file locations
Stops underscore in class name from being honored as directory separator
Makes implementations more explicitly interoperable
Cons:
Staying with PSR-0 for relatively deeper directory structures.
Pros:
Cons:
Leaves us with deeper directory structures
Leaves us with underscores in the class name being honored as directory separators
It couldn’t be referenced by other proposals. It was revealed as the preference.
Pros:
Cons:
It was not a long time ago that the law was taken. greater narrative and somewhat more imperative language. This approach was decried by a vocal minority of participants. After some time, PSR-0; She edited his opinion on the text.
This is a guideline. Failing to strip the leading namespace seperator could lead to unexpected behavior.
Too many others to name and count
Entrance Vote: https://groups.google.com/d/msg/php-fig/_LYBgfcEoFE/ZwFTvVTIl4AJ
Acceptance Vote:
1st attempt: https://groups.google.com/forum/#!topic/php-fig/Ua46E344_Ls, presented prior to new workflow; due to accidental modification
2nd attempt: https://groups.google.com/forum/#!topic/php-fig/NWfyAeF7Psk, cancelled at the discretion of the sponsor https://groups.google.com/forum/#!topic/php- fig / t4mW2TQF7iE
3rd attempt: TBD
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
This PSR describes the autoloading classes from file paths. It is fully interoperable, and it can be used in addition to any other autoloading specification, including PSR-0. This will be autoloaded according to the specification.
The term "class" refers to classes, interfaces, traits, and other similar structures.
A fully qualified class name has the following form:
\<NamespaceName>(\<SubNamespaceNames>)*\<ClassName> The fully qualified class name has been defined as a "vendor namespace".
MAY have one or more sub-namespace names.
MUST have terminating class name.
Underscores.
MAY BE ANY BATTERY AND ALTERNATIVE.
All class names MUST be referenced in a case-sensitive fashion.
When loading a file that corresponds to a fully qualified class name ...
If you’re looking for a new name, you’ll find out what you’re looking for (or "namespace prefix").
The contiguous sub-namespace names after the "namespace prefix" correspond to the subdirectory within a "base directory", in which the namespace separators are the directory separators. The subdirectory name MUST match the case of the sub-namespace names.
The terminating class name .php . The file name MUST match the case of the terminating class name.
MUST NOT return excerpts, MUST NOT return a value.
The table below shows the corresponding file path for the prefix, and the base directory.
| Fully Qualified Class Name | Namespace Prefix | Base directory | Resulting File Path |
|---|---|---|---|
| \ Acme \ Log \ Writer \ File_Writer | Acme \ Log \ Writer | ./acme-log-writer/lib/ | ./acme-log-writer/lib/File_Writer.php |
| \ Aura \ Web \ Response \ Status | Aura \ Web | / path / to / aura-web / src / | /path/to/aura-web/src/Response/Status.php |
| \ Symfony \ Core \ Request | Symfony \ core | ./vendor/Symfony/Core/ | ./vendor/Symfony/Core/Request.php |
| \ Zend \ Acl | Zend | / usr / includes / Zend / | /usr/includes/Zend/Acl.php |
For example implementations of autoloaders conforming to the specification, please see the examples file. MAY change at any time.
Comments
To leave a comment
Software and information systems development
Terms: Software and information systems development