opdavies/drupalcampbristol
Archived
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update to Drupal 8.0.0-beta15. For more information, see: https://www.drupal.org/node/2563023

Browse source
This commit is contained in:
Pantheon Automation 2015-09-04 13:20:09 -07:00 • committed by Greg Anderson
parent 2720a9ec4b
commit f3791f1da3
1898 changed files with 54300 additions and 11481 deletions
Download patch file Download diff file Expand all files Collapse all files

173
core/core.api.php
View file

@ -49,6 +49,7 @@
* - @link user_api User accounts, permissions, and roles @endlink
* - @link theme_render Render API @endlink
* - @link themeable Theme system @endlink
* - @link update_api Update API @endlink
* - @link migration Migration @endlink
*
* @section additional Additional topics
@ -230,11 +231,23 @@
* Whether or not configuration files are being used for the active
* configuration storage on a particular site, configuration files are always
* used for:
* - Defining the default configuration for a module, which is imported to the
* active storage when the module is enabled. Note that changes to this
* default configuration after a module is already enabled have no effect;
* to make a configuration change after a module is enabled, you would need
* to uninstall/reinstall or use a hook_update_N() function.
* - Defining the default configuration for an extension (module, theme, or
* profile), which is imported to the active storage when the extension if
* enabled. These configuration items are located in the config/install
* sub-directory of the extension. Note that changes to this configuration
* after a module or theme is already enabled have no effect; to make a
* configuration change after a module or theme is enabled, you would need to
* uninstall/reinstall or use a hook_update_N() function.
* - Defining optional configuration for a module or theme. Optional
* configuration items are located in the config/optional sub-directory of the
* extension. These configuration items have dependencies that are not
* explicit dependencies of the extension, so they are only installed if all
* dependencies are met. For example, in the scenario that module A defines a
* dependency which requires module B, but module A is installed first and
* module B some time later, then module A's config/optional directory will be
* scanned at that time for newly met dependencies, and the configuration will
* be installed then. If module B is never installed, the configuration item
* will not be installed either.
* - Exporting and importing configuration.
*
* The file storage format for configuration information in Drupal is
@ -318,9 +331,8 @@
* modulename.schema.yml file, with an entry for 'modulename.config_prefix.*'.
* For example, for the Role entity, the file user.schema.yml has an entry
* user.role.*; see @ref sec_yaml above for more information.
* - Your module may also provide a few configuration items to be installed by
* default, by adding configuration files to the module's config/install
* directory; see @ref sec_yaml above for more information.
* - Your module can provide default/optional configuration entities in YAML
* files; see @ref sec_yaml above for more information.
* - Some configuration entities have dependencies on other configuration
* entities, and module developers need to consider this so that configuration
* can be imported, uninstalled, and synchronized in the right order. For
@ -568,6 +580,9 @@
* $settings['cache']['default'] = 'cache.custom';
* @endcode
*
* Finally, you can chain multiple cache backends together, see
* \Drupal\Core\Cache\ChainedFastBackend and \Drupal\Core\Cache\BackendChain.
*
* @see https://www.drupal.org/node/1884796
* @}
*/
@ -830,42 +845,115 @@
* @{
* API for describing data based on a set of available data types.
*
* The Typed Data API was created to provide developers with a consistent
* interface for interacting with data, as well as an API for metadata
* (information about the data, such as the data type, whether it is
* translatable, and who can access it). The Typed Data API is used in several
* Drupal sub-systems, such as the Entity Field API and Configuration API.
* PHP has data types, such as int, string, float, array, etc., and it is an
* object-oriented language that lets you define classes and interfaces.
* However, in some cases, it is useful to be able to define an abstract
* type (as in an interface, free of implementation details), that still has
* properties (which an interface cannot) as well as meta-data. The Typed Data
* API provides this abstraction.
*
* @section sec_overview Overview
* Each data type in the Typed Data API is a plugin class (annotation class
* example: \Drupal\Core\TypedData\Annotation\DataType); these plugins are
* managed by the typed_data_manager service (by default
* \Drupal\Core\TypedData\TypedDataManager). Each data object encapsulates a
* single piece of data, provides access to the metadata, and provides
* validation capability. Also, the typed data plugins have a shorthand
* for easily accessing data values, described in @ref sec_tree.
*
* The metadata of a data object is defined by an object based on a class called
* the definition class (see \Drupal\Core\TypedData\DataDefinitionInterface).
* The class used can vary by data type and can be specified in the data type's
* plugin definition, while the default is set in the $definition_class property
* of the annotation class. The default class is
* \Drupal\Core\TypedData\DataDefinition. For data types provided by a plugin
* deriver, the plugin deriver can set the definition_class property too.
* The metadata object provides information about the data, such as the data
* type, whether it is translatable, the names of its properties (for complex
* types), and who can access it.
*
* See https://www.drupal.org/node/1794140 for more information about the Typed
* Data API.
*
* @section interfaces Interfaces and classes in the Typed Data API
* There are several basic interfaces in the Typed Data API, representing
* different types of data:
* - \Drupal\Core\TypedData\PrimitiveInterface: Used for primitive data, such
* as strings, numeric types, etc. Drupal provides primitive types for
* integers, strings, etc. based on this interface, and you should
* not ever need to create new primitive types.
* - \Drupal\Core\TypedData\TypedDataInterface: Used for single pieces of data,
* with some information about its context. Abstract base class
* \Drupal\Core\TypedData\TypedData is a useful starting point, and contains
* documentation on how to extend it.
* - \Drupal\Core\TypedData\ComplexDataInterface: Used for complex data, which
* contains named and typed properties; extends TypedDataInterface. Examples
* of complex data include content entities and field items. See the
* @link entity_api Entity API topic @endlink for more information about
* entities; for most complex data, developers should use entities.
* - \Drupal\Core\TypedData\ListInterface: Used for a sequential list of other
* typed data. Class \Drupal\Core\TypedData\Plugin\DataType\ItemList is a
* generic implementation of this interface, and it is used by default for
* data declared as a list of some other data type. You can also define a
* custom list class, in which case ItemList is a useful base class.
* @section sec_varieties Varieties of typed data
* There are three kinds of typed data: primitive, complex, and list.
*
* @section defining Defining data types
* @subsection sub_primitive Primitive data types
* Primitive data types wrap PHP data types and also serve as building blocks
* for complex and list typed data. Each primitive data type has an interface
* that extends \Drupal\Core\TypedData\PrimitiveInterface, with getValue()
* and setValue() methods for accessing the data value, and a default plugin
* implementation. Here's a list:
* - \Drupal\Core\TypedData\Type\IntegerInterface: Plugin ID integer,
* corresponds to PHP type int.
* - \Drupal\Core\TypedData\Type\StringInterface: Plugin ID string,
* corresponds to PHP type string.
* - \Drupal\Core\TypedData\Type\FloatInterface: Plugin ID float,
* corresponds to PHP type float.
* - \Drupal\Core\TypedData\Type\BooleanInterface: Plugin ID bool,
* corresponds to PHP type bool.
* - \Drupal\Core\TypedData\Type\BinaryInterface: Plugin ID binary,
* corresponds to a PHP file resource.
* - \Drupal\Core\TypedData\Type\UriInterface: Plugin ID uri.
*
* @subsection sec_complex Complex data
* Complex data types, with interface
* \Drupal\Core\TypedData\ComplexDataInterface, represent data with named
* properties; the properties can be accessed with get() and set() methods.
* The value of each property is itself a typed data object, which can be
* primitive, complex, or list data.
*
* The base type for most complex data is the
* \Drupal\Core\TypedData\Plugin\DataType\Map class, which represents an
* associative array. Map provides its own definition class in the annotation,
* \Drupal\Core\TypedData\MapDataDefinition, and most complex data classes
* extend this class. The getValue() and setValue() methods on the Map class
* enforce the data definition and its property structure.
*
* The Drupal Field API uses complex typed data for its field items, with
* definition class \Drupal\Core\Field\TypedData\FieldItemDataDefinition.
*
* @section sec_list Lists
* List data types, with interface \Drupal\Core\TypedData\ListInterface,
* represent data that is an ordered list of typed data, all of the same type.
* More precisely, the plugins in the list must have the same base plugin ID;
* however, some types (for example field items and entities) are provided by
* plugin derivatives and the sub IDs can be different.
*
* @section sec_tree Tree handling
* Typed data allows you to use shorthand to get data values nested in the
* implicit tree structure of the data. For example, to get the value from
* an entity field item, the Entity Field API allows you to call:
* @code
* $value = $entity->fieldName->propertyName;
* @endcode
* This is really shorthand for:
* @code
* $field_item_list = $entity->get('fieldName');
* $field_item = $field_item_list->get(0);
* $property = $field_item->get('propertyName');
* $value = $property->getValue();
* @endcode
* Some notes:
* - $property, $field_item, and $field_item_list are all typed data objects,
* while $value is a raw PHP value.
* - You can call $property->getParent() to get $field_item,
* $field_item->getParent() to get $field_item_list, or
* $field_item_list->getParent() to get $typed_entity ($entity wrapped in a
* typed data object). $typed_entity->getParent() is NULL.
* - For all of these ->getRoot() returns $typed_entity.
* - The langcode property is on $field_item_list, but you can access it
* on $property as well, so that all items will report the same langcode.
* - When the value of $property is changed by calling $property->setValue(),
* $property->onChange() will fire, which in turn calls the parent object's
* onChange() method and so on. This allows parent objects to react upon
* changes of contained properties or list items.
*
* @section sec_defining Defining data types
* To define a new data type:
* - Create a class that implements one of the Typed Data interfaces.
* Typically, you will want to extend one of the classes listed in the
* section above as a starting point.
* sections above as a starting point.
* - Make your class into a DataType plugin. To do that, put it in namespace
* \Drupal\yourmodule\Plugin\DataType (where "yourmodule" is your module's
* short name), and add annotation of type
@ -873,7 +961,7 @@
* See the @link plugin_api Plugin API topic @endlink and the
* @link annotation Annotations topic @endlink for more information.
*
* @section using Using data types
* @section sec_using Using data types
* The data types of the Typed Data API can be used in several ways, once they
* have been defined:
* - In the Field API, data types can be used as the class in the property
@ -882,6 +970,15 @@
* - In configuration schema files, you can use the unique ID ('id' annotation)
* from any DataType plugin class as the 'type' value for an entry. See the
* @link config_api Confuration API topic @endlink for more information.
* - If you need to create a typed data object in code, first get the
* typed_data_manager service from the container or by calling
* \Drupal::typedDataManager(). Then pass the plugin ID to
* $manager::createDataDefinition() to create an appropriate data definition
* object. Then pass the data definition object and the value of the data to
* $manager::create() to create a typed data object.
*
* @see plugin_api
* @see container
* @}
*/
@ -1000,7 +1097,7 @@
* verified with standard control structures at all times, not just checked in
* development environments with assert() statements on.
*
* When runtime assertions fail in PHP 7 an \AssertionException is thrown.
* When runtime assertions fail in PHP 7 an \AssertionError is thrown.
* Drupal uses an assertion callback to do the same in PHP 5.x so that unit
* tests involving runtime assertions will work uniformly across both versions.
*