AssetCollectionInterface.php

<?php

/*
 * This file is part of the Assetic package, an OpenSky project.
 *
 * (c) 2010-2013 OpenSky Project Inc
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */
namespace Assetic\Asset;


/**
 * An asset collection.
 *
 * @author Kris Wallsmith <kris.wallsmith@gmail.com>
 */
interface AssetCollectionInterface extends AssetInterface, \Traversable {

  /**
   * Returns all child assets.
   *
   * @return array An array of AssetInterface objects
   */
  public function all();

  /**
   * Adds an asset to the current collection.
   *
   * @param AssetInterface $asset An asset
   */
  public function add(AssetInterface $asset);

  /**
   * Removes a leaf.
   *
   * @param AssetInterface $leaf      The leaf to remove
   * @param Boolean        $graceful  Whether the failure should return false or throw an exception
   *
   * @return Boolean Whether the asset has been found
   *
   * @throws \InvalidArgumentException If the asset cannot be found
   */
  public function removeLeaf(AssetInterface $leaf, $graceful = false);

  /**
   * Replaces an existing leaf with a new one.
   *
   * @param AssetInterface $needle      The current asset to replace
   * @param AssetInterface $replacement The new asset
   * @param Boolean        $graceful  Whether the failure should return false or throw an exception
   *
   * @return Boolean Whether the asset has been found
   *
   * @throws \InvalidArgumentException If the asset cannot be found
   */
  public function replaceLeaf(AssetInterface $needle, AssetInterface $replacement, $graceful = false);

}