Data providers overhaul

README.md

@@ -4,34 +4,36 @@ The __CLDR__ package provides means to internationalize your application by leve
 data and conventions defined by the [Unicode Common Locale Data Repository](http://cldr.unicode.org/) (CLDR).
 
 The package targets the [CLDR version 26](http://cldr.unicode.org/index/downloads/cldr-26), from
-which data is retrieved when required. A stack of cache can be used to store and retrieve these
-data.
+which data is retrieved when required.
 
 
 
 
 
 ## Instantiating the repository
 
-The CLDR is represented by a [Repository][] instance, from which you can access
-the available locales or supplemental data. When necessary, the repository fetches the required
-data through a provider. You can use the default provider, or define your own.
+The CLDR is represented by a [Repository][] instance, from which data is accessed. When required,
+data is retrieved through a provider, and in order to avoid hitting the web with every request,
+a stack of them is used.
 
-The following example demonstrates how such a repository is instantiated and how the
-available locales and supplemental data are accessed:
+The following example demonstrates how a repository can be instantiated with a nice stack of
+providers. One fetches the data from the web, the other from the filesystem, and the last one
+from the runtime memory:
 
 ```php
 <?php
 
 namespace ICanBoogie\CLDR;
 
-$provider = new Provider
-(
-	new RunTimeCache(new FileCache('/path/to/cached_repository')),
-	new Retriever
-);
-
+$provider = new RunTimeProvider(new FileProvider(new WebProvider, "/path/to/storage"));
 $repository = new Repository($provider);
+```
+
+The following example demonstrates how the repository can be used to access locales and
+supplemental data:
+
+```php
+<?php
 
 $english_locale = $repository->locales['en'];
 $french_locale = $repository->locales['fr'];

lib/FileProvider.php

@@ -0,0 +1,104 @@
+<?php
+
+/*
+ * This file is part of the ICanBoogie package.
+ *
+ * (c) Olivier Laviale <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace ICanBoogie\CLDR;
+
+/**
+ * Provides CLDR data from the filesystem, and falls back to a specified provider when the data
+ * is not available.
+ */
+class FileProvider implements ProviderInterface, CacheInterface
+{
+	/**
+	 * Create a store key from a CLDR path.
+	 *
+	 * @param string $path A CLDR path.
+	 *
+	 * @return string A store key.
+	 */
+	static private function path_to_key($path)
+	{
+		return str_replace('/', '--', $path);
+	}
+
+	/**
+	 * The directory where files are stored.
+	 *
+	 * @var string
+	 */
+	protected $root;
+
+	/**
+	 * @var ProviderInterface
+	 */
+	protected $provider;
+
+	/**
+	 * @param ProviderInterface $provider Fallback provider.
+	 * @param string $directory Path to the directory where cached files are stored.
+	 */
+	public function __construct(ProviderInterface $provider, $directory)
+	{
+		$this->root = rtrim($directory, DIRECTORY_SEPARATOR) . DIRECTORY_SEPARATOR;
+		$this->provider = $provider;
+	}
+
+	public function exists($path)
+	{
+		$key = self::path_to_key($path);
+		$filename = $this->root . $key;
+
+		return file_exists($filename);
+	}
+
+	public function retrieve($path)
+	{
+		$key = self::path_to_key($path);
+		$filename = $this->root . $key;
+
+		if (!file_exists($filename))
+		{
+			return;
+		}
+
+		return json_decode(file_get_contents($filename), true);
+	}
+
+	public function store($path, $data)
+	{
+		$key = self::path_to_key($path);
+		$filename = $this->root . $key;
+
+		file_put_contents($filename, json_encode($data));
+	}
+
+	/**
+	 * The section path, following the pattern "<identity>/<section>".
+	 *
+	 * @param string $path
+	 *
+	 * @throws ResourceNotFound when the specified path does not exists on the CLDR source.
+	 *
+	 * @return string
+	 */
+	public function provide($path)
+	{
+		if ($this->exists($path))
+		{
+			return $this->retrieve($path);
+		}
+
+		$data = $this->provider->provide($path);
+		$this->store($path, $data);
+
+		return $data;
+	}
+}

lib/Locale.php

@@ -189,7 +189,7 @@ public function offsetGet($offset)
 				throw new OffsetNotDefined(array($offset, $this));
 			}
 
-			$data = $this->repository->provider->fetch("main/{$this->code}/{$offset}");
+			$data = $this->repository->fetch("main/{$this->code}/{$offset}");
 			$path = "main/{$this->code}/" . self::$available_sections[$offset];
 			$path_parts = explode('/', $path);
 

lib/ProviderInterface.php

@@ -0,0 +1,31 @@
+<?php
+
+/*
+ * This file is part of the ICanBoogie package.
+ *
+ * (c) Olivier Laviale <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace ICanBoogie\CLDR;
+
+/**
+ * An interface for classes that can provide CLDR data.
+ *
+ * @package ICanBoogie\CLDR
+ */
+interface ProviderInterface
+{
+	/**
+	 * The section path, following the pattern "<identity>/<section>".
+	 *
+	 * @param string $path
+	 *
+	 * @throws ResourceNotFound when the specified path does not exists on the CLDR source.
+	 *
+	 * @return string
+	 */
+	public function provide($path);
+}

lib/Repository.php

@@ -27,7 +27,7 @@
  * var_dump($repository->territories['FR']);
  * </pre>
  *
- * @property-read Provider $provider A CLDR provider.
+ * @property-read ProviderInterface $provider A CLDR provider.
  * @property-read LocaleCollection $locales Locale collection.
  * @property-read Supplemental $supplemental Representation of the "supplemental" section.
  * @property-read TerritoryCollection $territories Territory collection.
@@ -107,9 +107,9 @@ protected function get_currencies()
 	/**
 	 * Initializes the {@link $provider} property.
 	 *
-	 * @param Provider $provider
+	 * @param ProviderInterface $provider
 	 */
-	public function __construct(Provider $provider)
+	public function __construct(ProviderInterface $provider)
 	{
 		$this->provider = $provider;
 	}
@@ -129,14 +129,14 @@ public function __get($property)
 	/**
 	 * Fetches the data available at the specified path.
 	 *
-	 * Note: The method is forwarded to {@link Provider::fetch}.
+	 * Note: The method is forwarded to {@link Provider::provide}.
 	 *
 	 * @param string $path
 	 *
 	 * @return array
 	 */
 	public function fetch($path)
 	{
-		return $this->provider->fetch($path);
+		return $this->provider->provide($path);
 	}
 }