Updates PHPDocs & adds helpers

sergeymakinen · Aug 23, 2016 · 13ec675 · 13ec675
1 parent 63c55be
commit 13ec675
Show file tree

Hide file tree

Showing 22 changed files with 805 additions and 342 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,5 +1,5 @@
-.idea
+/.idea
 /vendor
-composer.phar
-phpunit.phar
-/phpunit.xml
+/composer.phar
+/composer.lock
+/phpunit.phar
diff --git a/Asset.php b/Asset.php
@@ -1,4 +1,11 @@
 <?php
+/**
+ * Facades for Yii 2
+ *
+ * @see       https://github.com/sergeymakinen/yii2-facades
+ * @copyright Copyright (c) 2016 Sergey Makinen (https://makinen.ru)
+ * @license   https://github.com/sergeymakinen/yii2-facades/blob/master/LICENSE The MIT License
+ */
 
 namespace sergeymakinen\facades;
 
@@ -8,49 +15,50 @@
  *
  * Facades Yii::$app->get('assetManager') component.
  *
+ * @see \yii\web\AssetManager
  * @method static \yii\base\Behavior attachBehavior(string $name, string|array|\yii\base\Behavior $behavior) Attaches a behavior to this component.
  * @method static attachBehaviors(array $behaviors) Attaches a list of behaviors to the component.
  * @method static array behaviors() Returns a list of behaviors that this component should behave as.
  * @method static null|\yii\base\Behavior detachBehavior(string $name) Detaches a behavior from the component.
  * @method static detachBehaviors() Detaches all behaviors from the component.
  * @method static ensureBehaviors() Makes sure that the behaviors declared in [[behaviors()]] are attached to this component.
+ * @method static callable getAfterCopy() Returns a PHP callback that is called after a sub-directory or file is successfully copied.
+ * @method static bool getAppendTimestamp() Returns whether to append a timestamp to the URL of every published asset.
+ * @method static array getAssetMap() Returns mapping from source asset files (keys) to target asset files (values).
  * @method static string|bool getAssetPath(\yii\web\AssetBundle $bundle, string $asset) Returns the actual file path for the specified asset.
  * @method static string getAssetUrl(\yii\web\AssetBundle $bundle, string $asset) Returns the actual URL for the specified asset.
+ * @method static string getBasePath() Returns the root directory storing the published asset files.
+ * @method static string getBaseUrl() Returns the base URL through which the published asset files can be accessed.
+ * @method static callable getBeforeCopy() Returns a PHP callback that is called before copying each sub-directory or file.
  * @method static null|\yii\base\Behavior getBehavior(string $name) Returns the named behavior object.
  * @method static \yii\base\Behavior[] getBehaviors() Returns all behaviors attached to this component.
  * @method static \yii\web\AssetBundle getBundle(string $name, bool $publish = true) Returns the named asset bundle.
+ * @method static array|bool getBundles() Returns list of asset bundle configurations.
  * @method static \yii\web\AssetConverterInterface getConverter() Returns the asset converter.
+ * @method static int getDirMode() Returns the permission to be set for newly generated asset directories.
+ * @method static int getFileMode() Returns the permission to be set for newly published asset files.
+ * @method static bool getForceCopy() Returns whether the directory being published should be copied even if it is found in the target directory.
+ * @method static callable getHashCallback() Returns a callback that will be called to produce hash for asset directory generation.
+ * @method static bool getLinkAssets() Returns whether to use symbolic link to publish asset files.
  * @method static string|bool getPublishedPath(string $path) Returns the published path of a file path.
  * @method static string|bool getPublishedUrl(string $path) Returns the URL of a published file path.
- * @method static callable getAfterCopy() Returns $afterCopy - a PHP callback that is called after a sub-directory or file is successfully copied.
- * @method static bool getAppendTimestamp() Returns $appendTimestamp - whether to append a timestamp to the URL of every published asset.
- * @method static array getAssetMap() Returns $assetMap - mapping from source asset files (keys) to target asset files (values).
- * @method static string getBasePath() Returns $basePath - the root directory storing the published asset files.
- * @method static string getBaseUrl() Returns $baseUrl - the base URL through which the published asset files can be accessed.
- * @method static callable getBeforeCopy() Returns $beforeCopy - a PHP callback that is called before copying each sub-directory or file.
- * @method static array|bool getBundles() Returns $bundles - list of asset bundle configurations.
- * @method static int getDirMode() Returns $dirMode - the permission to be set for newly generated asset directories.
- * @method static int getFileMode() Returns $fileMode - the permission to be set for newly published asset files.
- * @method static bool getForceCopy() Returns $forceCopy - whether the directory being published should be copied even if it is found in the target directory.
- * @method static callable getHashCallback() Returns $hashCallback - a callback that will be called to produce hash for asset directory generation.
- * @method static bool getLinkAssets() Returns $linkAssets - whether to use symbolic link to publish asset files.
  * @method static bool hasEventHandlers(string $name) Returns a value indicating whether there is any handler attached to the named event.
  * @method static bool off(string $name, callable $handler = null) Detaches an existing event handler from this component.
  * @method static on(string $name, callable $handler, mixed $data = null, bool $append = true) Attaches an event handler to an event.
  * @method static array publish(string $path, array $options = []) Publishes a file or a directory.
+ * @method static setAfterCopy(callable $value) Sets a PHP callback that is called after a sub-directory or file is successfully copied.
+ * @method static setAppendTimestamp(bool $value) Sets whether to append a timestamp to the URL of every published asset.
+ * @method static setAssetMap(array $value) Sets mapping from source asset files (keys) to target asset files (values).
+ * @method static setBasePath(string $value) Sets the root directory storing the published asset files.
+ * @method static setBaseUrl(string $value) Sets the base URL through which the published asset files can be accessed.
+ * @method static setBeforeCopy(callable $value) Sets a PHP callback that is called before copying each sub-directory or file.
+ * @method static setBundles(array|bool $value) Sets list of asset bundle configurations.
  * @method static setConverter(array|\yii\web\AssetConverterInterface $value) Sets the asset converter.
- * @method static setAfterCopy(callable $value) Sets $afterCopy - a PHP callback that is called after a sub-directory or file is successfully copied.
- * @method static setAppendTimestamp(bool $value) Sets $appendTimestamp - whether to append a timestamp to the URL of every published asset.
- * @method static setAssetMap(array $value) Sets $assetMap - mapping from source asset files (keys) to target asset files (values).
- * @method static setBasePath(string $value) Sets $basePath - the root directory storing the published asset files.
- * @method static setBaseUrl(string $value) Sets $baseUrl - the base URL through which the published asset files can be accessed.
- * @method static setBeforeCopy(callable $value) Sets $beforeCopy - a PHP callback that is called before copying each sub-directory or file.
- * @method static setBundles(array|bool $value) Sets $bundles - list of asset bundle configurations.
- * @method static setDirMode(int $value) Sets $dirMode - the permission to be set for newly generated asset directories.
- * @method static setFileMode(int $value) Sets $fileMode - the permission to be set for newly published asset files.
- * @method static setForceCopy(bool $value) Sets $forceCopy - whether the directory being published should be copied even if it is found in the target directory.
- * @method static setHashCallback(callable $value) Sets $hashCallback - a callback that will be called to produce hash for asset directory generation.
- * @method static setLinkAssets(bool $value) Sets $linkAssets - whether to use symbolic link to publish asset files.
+ * @method static setDirMode(int $value) Sets the permission to be set for newly generated asset directories.
+ * @method static setFileMode(int $value) Sets the permission to be set for newly published asset files.
+ * @method static setForceCopy(bool $value) Sets whether the directory being published should be copied even if it is found in the target directory.
+ * @method static setHashCallback(callable $value) Sets a callback that will be called to produce hash for asset directory generation.
+ * @method static setLinkAssets(bool $value) Sets whether to use symbolic link to publish asset files.
  * @method static trigger(string $name, \yii\base\Event $event = null) Triggers an event.
  */
 class Asset extends Facade

diff --git a/Auth.php b/Auth.php
@@ -1,4 +1,11 @@
 <?php
+/**
+ * Facades for Yii 2
+ *
+ * @see       https://github.com/sergeymakinen/yii2-facades
+ * @copyright Copyright (c) 2016 Sergey Makinen (https://makinen.ru)
+ * @license   https://github.com/sergeymakinen/yii2-facades/blob/master/LICENSE The MIT License
+ */
 
 namespace sergeymakinen\facades;
 
@@ -8,6 +15,7 @@
  *
  * Facades Yii::$app->get('auth') component.
  *
+ * @see \yii\rbac\ManagerInterface
  * @method static bool add(\yii\rbac\Role|\yii\rbac\Permission|\yii\rbac\Rule $object) Adds a role, permission or rule to the RBAC system.
  * @method static bool addChild(\yii\rbac\Item $parent, \yii\rbac\Item $child) Adds an item as a child of another item.
  * @method static \yii\rbac\Assignment assign(\yii\rbac\Role $role, string|int $userId) Assigns a role to a user.

diff --git a/Cache.php b/Cache.php
@@ -1,4 +1,11 @@
 <?php
+/**
+ * Facades for Yii 2
+ *
+ * @see       https://github.com/sergeymakinen/yii2-facades
+ * @copyright Copyright (c) 2016 Sergey Makinen (https://makinen.ru)
+ * @license   https://github.com/sergeymakinen/yii2-facades/blob/master/LICENSE The MIT License
+ */
 
 namespace sergeymakinen\facades;
 
@@ -8,6 +15,7 @@
  *
  * Facades Yii::$app->get('cache') component.
  *
+ * @see \yii\caching\Cache
  * @method static bool add(mixed $key, mixed $value, int $duration = 0, \yii\caching\Dependency $dependency = null) Stores a value identified by a key into cache if the cache does not contain this key.
  * @method static \yii\base\Behavior attachBehavior(string $name, string|array|\yii\base\Behavior $behavior) Attaches a behavior to this component.
  * @method static attachBehaviors(array $behaviors) Attaches a list of behaviors to the component.
@@ -19,11 +27,10 @@
  * @method static ensureBehaviors() Makes sure that the behaviors declared in [[behaviors()]] are attached to this component.
  * @method static bool exists(mixed $key) Checks whether a specified key exists in the cache.
  * @method static bool flush() Deletes all values from cache.
- * @method static mixed get(mixed $key) Retrieves a value from cache with a specified key.
  * @method static null|\yii\base\Behavior getBehavior(string $name) Returns the named behavior object.
  * @method static \yii\base\Behavior[] getBehaviors() Returns all behaviors attached to this component.
- * @method static string getKeyPrefix() Returns $keyPrefix - a string prefixed to every cache key so that it is unique globally in the whole cache storage.
- * @method static array|bool getSerializer() Returns $serializer - the functions used to serialize and unserialize cached data.
+ * @method static string getKeyPrefix() Returns a string prefixed to every cache key so that it is unique globally in the whole cache storage.
+ * @method static array|bool getSerializer() Returns the functions used to serialize and unserialize cached data.
  * @method static bool hasEventHandlers(string $name) Returns a value indicating whether there is any handler attached to the named event.
  * @method static bool madd(array $items, int $duration = 0, \yii\caching\Dependency $dependency = null) Stores multiple items in cache.
  * @method static array mget(string[] $keys) Retrieves multiple values from cache with the specified keys.
@@ -34,8 +41,8 @@
  * @method static bool off(string $name, callable $handler = null) Detaches an existing event handler from this component.
  * @method static on(string $name, callable $handler, mixed $data = null, bool $append = true) Attaches an event handler to an event.
  * @method static bool set(mixed $key, mixed $value, int $duration = 0, \yii\caching\Dependency $dependency = null) Stores a value identified by a key into cache.
- * @method static setKeyPrefix(string $value) Sets $keyPrefix - a string prefixed to every cache key so that it is unique globally in the whole cache storage.
- * @method static setSerializer(array|bool $value) Sets $serializer - the functions used to serialize and unserialize cached data.
+ * @method static setKeyPrefix(string $value) Sets a string prefixed to every cache key so that it is unique globally in the whole cache storage.
+ * @method static setSerializer(array|bool $value) Sets the functions used to serialize and unserialize cached data.
  * @method static trigger(string $name, \yii\base\Event $event = null) Triggers an event.
  */
 class Cache extends Facade
@@ -47,4 +54,62 @@ public static function getFacadeComponentId()
     {
         return 'cache';
     }
+
+    /**
+     * Retrieves a value from cache with a specified key.
+     *
+     * @param mixed $key a key identifying the cached value. This can be a simple string or
+     * a complex data structure consisting of factors representing the key.
+     * @param callable|mixed $default a default value. This can also be any callable function that
+     * will recieve the key and should return a value.
+     *
+     * @return mixed the value stored in cache or the default value if the value is not in the cache, expired,
+     * or the dependency associated with the cached data has changed.
+     */
+    public static function get($key, $default = false)
+    {
+        $value = static::getFacadeComponent()->get($key);
+        if ($value === false) {
+            if ($default instanceof \Closure) {
+                $value = call_user_func($default, $key);
+            } else {
+                $value = $default;
+            }
+        }
+        return $value;
+    }
+
+    /**
+     * Retrieves a value from cache (or stores it if it's not cached) with a specified key.
+     * If the cache already contains such a key, it will be returned, else the default value
+     * will be stored in the cache and returned.
+     *
+     * @param mixed $key a key identifying the cached value. This can be a simple string or
+     * a complex data structure consisting of factors representing the key.
+     * @param callable|mixed $default the value to be cached and retrieved if some value is not already in the cache. This can also be
+     * any callable function that will recieve the key and should return a value.
+     * @param int $duration the number of seconds in which the cached value will expire. 0 means never expire.
+     * @param \yii\caching\Dependency $dependency dependency of the cached item. If the dependency changes,
+     * the corresponding value in the cache will be invalidated when it is fetched via [[get()]].
+     * This parameter is ignored if [[serializer]] is false.
+     *
+     * @return bool whether the value is successfully stored into cache
+     */
+    public static function getOrSet($key, $default, $duration = 0, $dependency = null)
+    {
+        /**
+         * @var \yii\caching\Cache $cache
+         */
+        $cache = static::getFacadeComponent();
+        $value = $cache->get($key);
+        if ($value === false) {
+            if ($default instanceof \Closure) {
+                $value = call_user_func($default, $key);
+            } else {
+                $value = $default;
+            }
+            $cache->set($key, $value, $duration, $dependency);
+        }
+        return $value;
+    }
 }