1: <?php
  2: 
  3: namespace Charcoal\Source;
  4: 
  5: // Intra-module (`charcoal-core`) dependencies
  6: use \Charcoal\Model\ModelInterface;
  7: use \Charcoal\Source\StorableInterface;
  8: 
  9: /**
 10:  * @todo Implement SourceInterface.
 11:  */
 12: interface SourceInterface
 13: {
 14:     /**
 15:      * @param ModelInterface $model The source's model.
 16:      * @return AbstractSource Chainable
 17:      */
 18:     public function setModel(ModelInterface $model);
 19: 
 20:     /**
 21:      * @return ModelInterface
 22:      */
 23:     public function model();
 24: 
 25:     /**
 26:      * @param mixed             $ident The ID of the item to load.
 27:      * @param StorableInterface $item  Optional item to load into.
 28:      * @return StorableInterface
 29:      */
 30:     public function loadItem($ident, StorableInterface $item = null);
 31: 
 32:     /**
 33:      * @param StorableInterface|null $item The item type to load.
 34:      * @return array
 35:      */
 36:     public function loadItems(StorableInterface $item = null);
 37: 
 38:     /**
 39:      * Save an item (create a new row) in storage.
 40:      *
 41:      * @param StorableInterface $item The object to save.
 42:      * @return mixed The created item ID, or false in case of an error.
 43:      */
 44:     public function saveItem(StorableInterface $item);
 45: 
 46:     /**
 47:      * Update an item in storage.
 48:      *
 49:      * @param StorableInterface $item       The object to update.
 50:      * @param array             $properties The list of properties to update, if not all.
 51:      * @return boolean Success / Failure
 52:      */
 53:     public function updateItem(StorableInterface $item, array $properties = null);
 54: 
 55:     /**
 56:      * Delete an item from storage
 57:      *
 58:      * @param StorableInterface $item Optional item to delete. If none, the current model object will be used.
 59:      * @return boolean Success / Failure
 60:      */
 61:     public function deleteItem(StorableInterface $item = null);
 62: 
 63:     /**
 64:      * @param array $properties The properties.
 65:      * @return ColelectionLoader Chainable
 66:      */
 67:     public function setProperties(array $properties);
 68: 
 69:     /**
 70:      * @return array
 71:      */
 72:     public function properties();
 73: 
 74:     /**
 75:      * @param string $property Property ident.
 76:      * @return CollectionLoader Chainable
 77:      */
 78:     public function addProperty($property);
 79: 
 80:     /**
 81:      * @param array $filters The filters.
 82:      * @return Collection Chainable
 83:      */
 84:     public function setFilters(array $filters);
 85: 
 86:     /**
 87:      * @return array
 88:      */
 89:     public function filters();
 90: 
 91:     /**
 92:      * Add a collection filter to the loader.
 93:      *
 94:      * @param string|array|Filter $param   The filter parameter. May the "filter property" or an array / object.
 95:      * @param mixed               $val     Optional. Val, only used if the first argument is a string.
 96:      * @param array               $options Optional. Options, only used if the first argument is a string.
 97:      * @return CollectionLoader (Chainable)
 98:      */
 99:     public function addFilter($param, $val = null, array $options = null);
100: 
101:     /**
102:      * @param array $orders The orders.
103:      * @return CollectionLoader Chainable
104:      */
105:     public function setOrders(array $orders);
106: 
107:     /**
108:      * @return array
109:      */
110:     public function orders();
111: 
112:     /**
113:      * @param string|array|Order $param   The order parameter. May the "order property" or an array / object.
114:      * @param string             $mode    Optional. Mode, only used if the first argument is a string.
115:      * @param array              $options Optional. Options, only user if the first argument is a string.
116:      * @return CollectionLoader Chainable
117:      */
118:     public function addOrder($param, $mode = 'asc', array $options = null);
119: 
120:     /**
121:      * @param mixed $param The pagination information.
122:      * @return CollectionLoader Chainable
123:      */
124:     public function setPagination($param);
125: 
126:     /**
127:      * @return Pagination
128:      */
129:     public function pagination();
130: 
131:     /**
132:      * @param integer $page The page number. Starts with 0.
133:      * @return CollectionLoader Chainable
134:      */
135:     public function setPage($page);
136: 
137:     /**
138:      * @return integer
139:      */
140:     public function page();
141: 
142:     /**
143:      * @param integer $num The number of item to retrieve per page.
144:      * @return CollectionLoader Chainable
145:      */
146:     public function setNumPerPage($num);
147: 
148:     /**
149:      * @return integer
150:      */
151:     public function numPerPage();
152: }
153: