15079837495

Committed 17 May 2025 12:41AM UTC coverage: 95.465% (-0.2%) from 95.642%

Build Type

push

github

Committed by

Commit Message

readme: added info about custom mappers

Run Details

421 of 441 relevant lines covered (95.46%)

0.95 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

96.77

/src/Assets/Registry.php

<?php

declare(strict_types=1);

namespace Nette\Assets;


/**
 * Manages a collection of named asset Mappers and provides a central point
 * for retrieving Assets using qualified references (mapper:reference).
 * Includes a simple cache for resolved assets.
 */
class Registry
{
        public const DefaultScope = 'default';
        private const MaxCacheSize = 100;

        /** @var array<string, Mapper> */
        private array $mappers = [];

        /** @var array<string, Asset> */
        private array $cache = [];


        /**
         * Registers a new asset mapper under a specific identifier.
         * @throws \InvalidArgumentException If the identifier is already in use.
         */
        public function addMapper(string $id, Mapper $mapper): void
        {
                if (isset($this->mappers[$id])) {
                        throw new \InvalidArgumentException("Asset mapper '$id' is already registered");
                }
                $this->mappers[$id] = $mapper;
        }


        /**
         * Retrieves a registered asset mapper by its identifier.
         * @throws \InvalidArgumentException If the requested mapper identifier is unknown.
         */
        public function getMapper(string $id = self::DefaultScope): Mapper
        {
                return $this->mappers[$id] ?? throw new \InvalidArgumentException("Unknown asset mapper '$id'.");
        }


        /**
         * Retrieves an Asset instance using a qualified reference. Accepts either 'mapper:reference' or ['mapper', 'reference'].
         * Options passed directly to the underlying Mapper::getAsset() method.
         * @throws AssetNotFoundException when the asset cannot be found
         */
        public function getAsset(string|array $qualifiedRef, array $options = []): Asset
        {
                [$mapper, $reference] = is_string($qualifiedRef)
                        ? Helpers::parseReference($qualifiedRef)
                        : $qualifiedRef;

                $mapperDef = $mapper ?? self::DefaultScope;
                $reference = (string) $reference;
                $cacheKey = $this->generateCacheKey($mapperDef, $reference, $options);
                if ($cacheKey !== null && array_key_exists($cacheKey, $this->cache)) {
                        return $this->cache[$cacheKey];
                }

                try {
                        $asset = $this->getMapper($mapperDef)->getAsset($reference, $options);

                        if (count($this->cache) >= self::MaxCacheSize) {
                                array_shift($this->cache); // remove the oldest entry
                        }

                        return $this->cache[$cacheKey] = $asset;
                } catch (AssetNotFoundException $e) {
                        throw $mapper ? $e->qualifyReference($mapperDef, $reference) : $e;
                }
        }


        /**
         * Attempts to retrieve an Asset instance using a qualified reference, but returns null if not found.
         * Accepts either 'mapper:reference' or ['mapper', 'reference'].
         * Options passed directly to the underlying Mapper::getAsset() method.
         */
        public function tryGetAsset(string|array $qualifiedRef, array $options = []): ?Asset
        {
                try {
                        return $this->getAsset($qualifiedRef, $options);
                } catch (AssetNotFoundException) {
                        return null;
                }
        }


        private function generateCacheKey(string $mapper, string $reference, array $options): ?string
        {
                foreach ($options as $item) {
                        if (!$item !== null && !is_scalar($item)) {
                                return null;
                        }
                }
                return $mapper . ':' . $reference . ($options ? ':' . hash('xxh128', serialize($options)) : '');
        }
}

1	<?php
2
3	declare(strict_types=1);
4
5	namespace Nette\Assets;
6
7
8	/**
9	* Manages a collection of named asset Mappers and provides a central point
10	* for retrieving Assets using qualified references (mapper:reference).
11	* Includes a simple cache for resolved assets.
12	*/
13	class Registry
14	{
15	public const DefaultScope = 'default';
16	private const MaxCacheSize = 100;
17
18	/** @var array<string, Mapper> */
19	private array $mappers = [];
20
21	/** @var array<string, Asset> */
22	private array $cache = [];
23
24
25	/**
26	* Registers a new asset mapper under a specific identifier.
27	* @throws \InvalidArgumentException If the identifier is already in use.
28	*/
29	public function addMapper(string $id, Mapper $mapper): void	1✔
30	{
31	if (isset($this->mappers[$id])) {	1✔
32	throw new \InvalidArgumentException("Asset mapper '$id' is already registered");	1✔
33	}
34	$this->mappers[$id] = $mapper;	1✔
35	}	1✔
36
37
38	/**
39	* Retrieves a registered asset mapper by its identifier.
40	* @throws \InvalidArgumentException If the requested mapper identifier is unknown.
41	*/
42	public function getMapper(string $id = self::DefaultScope): Mapper	1✔
43	{
44	return $this->mappers[$id] ?? throw new \InvalidArgumentException("Unknown asset mapper '$id'.");	1✔
45	}
46
47
48	/**
49	* Retrieves an Asset instance using a qualified reference. Accepts either 'mapper:reference' or ['mapper', 'reference'].
50	* Options passed directly to the underlying Mapper::getAsset() method.
51	* @throws AssetNotFoundException when the asset cannot be found
52	*/
53	public function getAsset(string\|array $qualifiedRef, array $options = []): Asset	1✔
54	{
55	[$mapper, $reference] = is_string($qualifiedRef)	1✔
56	? Helpers::parseReference($qualifiedRef)	1✔
57	: $qualifiedRef;	1✔
58
59	$mapperDef = $mapper ?? self::DefaultScope;	1✔
60	$reference = (string) $reference;	1✔
61	$cacheKey = $this->generateCacheKey($mapperDef, $reference, $options);	1✔
62	if ($cacheKey !== null && array_key_exists($cacheKey, $this->cache)) {	1✔
63	return $this->cache[$cacheKey];	1✔
64	}
65
66	try {
67	$asset = $this->getMapper($mapperDef)->getAsset($reference, $options);	1✔
68
69	if (count($this->cache) >= self::MaxCacheSize) {	1✔
70	array_shift($this->cache); // remove the oldest entry	1✔
71	}
72
73	return $this->cache[$cacheKey] = $asset;	1✔
74	} catch (AssetNotFoundException $e) {	1✔
75	throw $mapper ? $e->qualifyReference($mapperDef, $reference) : $e;	1✔
76	}
77	}
78
79
80	/**
81	* Attempts to retrieve an Asset instance using a qualified reference, but returns null if not found.
82	* Accepts either 'mapper:reference' or ['mapper', 'reference'].
83	* Options passed directly to the underlying Mapper::getAsset() method.
84	*/
85	public function tryGetAsset(string\|array $qualifiedRef, array $options = []): ?Asset	1✔
86	{
87	try {
88	return $this->getAsset($qualifiedRef, $options);	1✔
89	} catch (AssetNotFoundException) {	1✔
90	return null;	1✔
91	}
92	}
93
94
95	private function generateCacheKey(string $mapper, string $reference, array $options): ?string	1✔
96	{
97	foreach ($options as $item) {	1✔
98	if (!$item !== null && !is_scalar($item)) {	1✔
99	return null;	×
100	}
101	}
102	return $mapper . ':' . $reference . ($options ? ':' . hash('xxh128', serialize($options)) : '');	1✔
103	}
104	}

nette / assets / 15079837495

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous