core.api.php 15.7 KB
 1 2 3 4 5 6 7 8 9 10 11 getCurrentLanguage()->id(); * * $data = NULL; * if ($cache = \Drupal::cache()->get($cid)) { *$data = $cache->data; * } * else { *$data = my_module_complicated_calculation(); * \Drupal::cache()->set($cid,$data); * } * @endcode * * @section bins Cache bins * * Cache storage is separated into "bins", each containing various cache items. * Each bin can be configured separately; see @ref configuration. * * When you request a cache object, you can specify the bin name in your call to * \Drupal::cache(). Alternatively, you can request a bin by getting service * "cache.nameofbin" from the container. The default bin is called "cache", with  224 225  * service name "cache.cache", it is used to store common and frequently used * caches like plugin information.  226  *  227 228 229 230 231  * Other common cache bins are the following: * - bootstrap: Small caches needed for the bootstrap on every request. * - render: Contains cached HTML strings like cached pages and blocks, can * grow to large size. * - data: Contains data that can vary by path or similar context.  232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309  * * A module can define a cache bin by defining a service in its * modulename.services.yml file as follows (substituting the desired name for * "nameofbin"): * @code * cache.nameofbin: * class: Drupal\Core\Cache\CacheBackendInterface * tags: * - { name: cache.bin } * factory_method: get * factory_service: cache_factory * arguments: [nameofbin] * @endcode * * @section delete Deletion * * There are two ways to remove an item from the cache: * - Deletion (using delete(), deleteMultiple() or deleteAll()) permanently * removes the item from the cache. * - Invalidation (using invalidate(), invalidateMultiple() or invalidateAll()) * is a "soft" delete that only marks items as "invalid", meaning "not fresh" * or "not fresh enough". Invalid items are not usually returned from the * cache, so in most ways they behave as if they have been deleted. However, * it is possible to retrieve invalid items, if they have not yet been * permanently removed by the garbage collector, by passing TRUE as the second * argument for get($cid,$allow_invalid). * * Use deletion if a cache item is no longer useful; for instance, if the item * contains references to data that has been deleted. Use invalidation if the * cached item may still be useful to some callers until it has been updated * with fresh data. The fact that it was fresh a short while ago may often be * sufficient. * * Invalidation is particularly useful to protect against stampedes. Rather than * having multiple concurrent requests updating the same cache item when it * expires or is deleted, there can be one request updating the cache, while the * other requests can proceed using the stale value. As soon as the cache item * has been updated, all future requests will use the updated value. * * @section tags Cache Tags * * The fourth argument of the set() method can be used to specify cache tags, * which are used to identify what type of data is included in each cache. Each * cache can have multiple tags, and each tag has a string key and a value. The * value can be: * - TRUE, to indicate that this type of data is present in the cache. * - An array of values. For example, the "node" tag indicates that particular * nodes' data is present in the cache, so its value is an array of node IDs. * Data that has been tagged can be deleted or invalidated as a group. * * Example: * @code * // A cache item with nodes, users, and some custom module data. * $tags = array( * 'my_custom_tag' => TRUE, * 'node' => array(1, 3), * 'user' => array(7), * ); * \Drupal::cache()->set($cid, $data, CacheBackendInterface::CACHE_PERMANENT,$tags); * * // Delete or invalidate all caches with certain tags. * \Drupal\Core\Cache\Cache::deleteTags(array('node' => array(1)); * \Drupal\Core\Cache\Cache::invalidateTags(array('user' => array(1))); * @endcode * * @todo Update cache tag deletion in https://drupal.org/node/918538 * * @todo Extend entity cache tags based on https://drupal.org/node/2217749 * * @section configuration Configuration * * Each cache bin can be configured separately; for instance, each bin can use a * different cache backend, such as APC or Memcache. The default backend stores * the cached data in the Drupal database. * * In a settings.php file, you can override the class used for a particular * cache bin. For example, if your implementation of * \Drupal\Core\Cache\CacheBackendInterface was called MyCustomCache, the  310  * following line would make Drupal use it for the 'cache_render' bin:  311  * @code  312  * $settings['cache_classes']['cache_render'] = 'Drupal\full\namespace\to\MyCustomCache';  313 314 315 316 317 318 319  * @endcode * * Additionally, you can register your cache implementation to be used by * default for all cache bins with: * @code *$settings['cache_classes']['cache'] = 'Drupal\full\namespace\to\MyCustomCache'; * @endcode  320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400  * * @see https://drupal.org/node/1884796 * @} */ /** * @defgroup user_api User Accounts System * @{ * API for user accounts, access checking, roles, and permissions. * * @todo write this * * Additional documentation paragraphs need to be written, and functions, * classes, and interfaces need to be added to this topic. * @} */ /** * @defgroup theme_render Theme system and Render API * @{ * Overview of the theme system and render API * * @todo write this * * Additional documentation paragraphs need to be written, and functions, * classes, and interfaces need to be added to this topic. * @} */ /** * @defgroup container Services and Dependency Injection Container * @{ * Overview of the Dependency Injection Container and Services. * * @todo write this * * Additional documentation paragraphs need to be written, and functions, * classes, and interfaces need to be added to this topic. * * See https://drupal.org/node/2133171 * @} */ /** * @defgroup typed_data Typed Data API * @{ * API for defining what type of data is used in fields, configuration, etc. * * @todo write this * * Additional documentation paragraphs need to be written, and functions, * classes, and interfaces need to be added to this topic. * * See https://drupal.org/node/1794140 * @} */ /** * @defgroup migration Migration API * @{ * Overview of the Migration API, which migrates data into Drupal. * * @todo write this * * Additional documentation paragraphs need to be written, and functions, * classes, and interfaces need to be added to this topic. * * See https://drupal.org/node/2127611 * @} */ /** * @defgroup testing Automated tests * @{ * Overview of PHPUnit tests and Simpletest tests. * * @todo write this * * Additional documentation paragraphs need to be written, and functions, * classes, and interfaces need to be added to this topic. *  401  * See https://drupal.org/simpletest and https://drupal.org/phpunit  402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452  * @} */ /** * @defgroup architecture Architecture overview * @{ * Overview of Drupal's architecture for developers. * * @todo write this * * Additional documentation paragraphs need to be written, and functions, * classes, and interfaces need to be added to this topic. * * Should include: modules, info.yml files, location of files, etc. * @} */ /** * @defgroup extending Extending Drupal * @{ * Overview of hooks, plugins, annotations, event listeners, and services. * * @todo write this * * Additional documentation paragraphs need to be written, and functions, * classes, and interfaces need to be added to this topic. This should be * high-level and link to more detailed topics. * @} */ /** * @defgroup oo_conventions Objected-oriented programming conventions * @{ * PSR-4, namespaces, class naming, and other conventions. * * @todo write this * * Additional documentation paragraphs need to be written, and functions, * classes, and interfaces need to be added to this topic. * * See https://drupal.org/node/608152 and links therein for references. This * should be an overview and link to details. It needs to cover: PSR-*, * namespaces, link to reference on OO, class naming conventions (base classes, * etc.), and other things developers should know related to object-oriented * coding. * @} */ /** * @defgroup best_practices Best practices for developers * @{  453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471  * Overview of standards and best practices for developers * * Ideally, all code that is included in Drupal Core and contributed modules, * themes, and distributions will be secure, internationalized, maintainable, * and efficient. In order to facilitate this, the Drupal community has * developed a set of guidelines and standards for developers to follow. Most of * these standards can be found under * @link https://drupal.org/developing/best-practices Best practices on Drupal.org @endlink * * Standards and best practices that developers should be aware of include: * - Security: https://drupal.org/writing-secure-code and the * @link sanitization Sanitization functions topic @endlink * - Coding standards: https://drupal.org/coding-standards * and https://drupal.org/coding-standards/docs * - Accessibility: https://drupal.org/node/1637990 (modules) and * https://drupal.org/node/464472 (themes) * - Usability: https://drupal.org/ui-standards * - Internationalization: @link i18n Internationalization topic @endlink * - Automated testing: @link testing Automated tests topic @endlink  472 473  * @} */