22312221661

Committed 23 Feb 2026 03:14PM UTC coverage: 94.106% (+0.06%) from 94.048%

Build Type

push

github

Committed by

Commit Message

added CLAUDE.md

Coverage Stats

495 of 526 relevant lines covered (94.11%)

0.94 hits per line

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

97.06

/src/Assets/Registry.php

<?php declare(strict_types=1);

namespace Nette\Assets;

use function array_key_exists, array_shift, count, hash, is_scalar, is_string, serialize;


/**
 * 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.
         * @param  string|array{?string, string}  $qualifiedRef
         * @param  array<string, mixed>  $options
         * @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
                        }

                        if ($cacheKey !== null) {
                                $this->cache[$cacheKey] = $asset;
                        }
                        return $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.
         * @param  string|array{string|null, string}  $qualifiedRef
         * @param  array<string, mixed>  $options
         */
        public function tryGetAsset(string|array $qualifiedRef, array $options = []): ?Asset
        {
                try {
                        return $this->getAsset($qualifiedRef, $options);
                } catch (AssetNotFoundException) {
                        return null;
                }
        }


        /**
         * @param array<string, mixed>  $options
         */
        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 declare(strict_types=1);	1✔
2
3	namespace Nette\Assets;
4
5	use function array_key_exists, array_shift, count, hash, is_scalar, is_string, serialize;
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	* @param string\|array{?string, string} $qualifiedRef
52	* @param array<string, mixed> $options
53	* @throws AssetNotFoundException when the asset cannot be found
54	*/
55	public function getAsset(string\|array $qualifiedRef, array $options = []): Asset	1✔
56	{
57	[$mapper, $reference] = is_string($qualifiedRef)	1✔
58	? Helpers::parseReference($qualifiedRef)	1✔
59	: $qualifiedRef;	1✔
60
61	$mapperDef = $mapper ?? self::DefaultScope;	1✔
62	$reference = (string) $reference;	1✔
63	$cacheKey = $this->generateCacheKey($mapperDef, $reference, $options);	1✔
64	if ($cacheKey !== null && array_key_exists($cacheKey, $this->cache)) {	1✔
65	return $this->cache[$cacheKey];	1✔
66	}
67
68	try {
69	$asset = $this->getMapper($mapperDef)->getAsset($reference, $options);	1✔
70
71	if (count($this->cache) >= self::MaxCacheSize) {	1✔
72	array_shift($this->cache); // remove the oldest entry	1✔
73	}
74
75	if ($cacheKey !== null) {	1✔
76	$this->cache[$cacheKey] = $asset;	1✔
77	}
78	return $asset;	1✔
79
80	} catch (AssetNotFoundException $e) {	1✔
81	throw $mapper ? $e->qualifyReference($mapperDef, $reference) : $e;	1✔
82	}
83	}
84
85
86	/**
87	* Attempts to retrieve an Asset instance using a qualified reference, but returns null if not found.
88	* Accepts either 'mapper:reference' or ['mapper', 'reference'].
89	* Options passed directly to the underlying Mapper::getAsset() method.
90	* @param string\|array{string\|null, string} $qualifiedRef
91	* @param array<string, mixed> $options
92	*/
93	public function tryGetAsset(string\|array $qualifiedRef, array $options = []): ?Asset	1✔
94	{
95	try {
96	return $this->getAsset($qualifiedRef, $options);	1✔
97	} catch (AssetNotFoundException) {	1✔
98	return null;	1✔
99	}
100	}
101
102
103	/**
104	* @param array<string, mixed> $options
105	*/
106	private function generateCacheKey(string $mapper, string $reference, array $options): ?string	1✔
107	{
108	foreach ($options as $item) {	1✔
109	if ($item !== null && !is_scalar($item)) {	1✔
110	return null;	×
111	}
112	}
113	return $mapper . ':' . $reference . ($options ? ':' . hash('xxh128', serialize($options)) : '');	1✔
114	}
115	}

nette / assets / 22312221661

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