1: <?php
  2: 
  3: namespace Charcoal\Source;
  4: 
  5: use \InvalidArgumentException;
  6: 
  7: // From 'charcoal-core'
  8: use \Charcoal\Source\OrderInterface;
  9: 
 10: /**
 11:  * Order
 12:  *
 13:  * Available modes:
 14:  * - `asc` to order in ascending (A-Z / 0-9) order.
 15:  * - `desc` to order in descending (Z-A / 9-0) order.
 16:  * - `rand` to order in a random fashion.
 17:  * - `values` to order by a defined array of properties.
 18:  * - `custom` to order by a custom SQL string.
 19:  */
 20: class Order implements OrderInterface
 21: {
 22:     const MODE_ASC = 'asc';
 23:     const MODE_DESC = 'desc';
 24:     const MODE_RANDOM = 'rand';
 25:     const MODE_VALUES = 'values';
 26:     const MODE_CUSTOM = 'custom';
 27: 
 28:     /**
 29:      * The model property (SQL column).
 30:      *
 31:      * @var string
 32:      */
 33:     protected $property;
 34: 
 35:     /**
 36:      * The sort mode.
 37:      *
 38:      * @var string
 39:      */
 40:     protected $mode;
 41: 
 42:     /**
 43:      * The values when {@see self::$mode} is {@see self::MODE_VALUES}.
 44:      *
 45:      * @var array
 46:      */
 47:     protected $values;
 48: 
 49:     /**
 50:      * Raw SQL clause when {@see self::$mode} is {@see self::MODE_CUSTOM}.
 51:      *
 52:      * @var string
 53:      */
 54:     protected $string;
 55: 
 56:     /**
 57:      * Whether the order is active.
 58:      *
 59:      * @var boolean
 60:      */
 61:     protected $active = true;
 62: 
 63:     /**
 64:      * @param array $data The order data.
 65:      * @return Order Chainable
 66:      */
 67:     public function setData(array $data)
 68:     {
 69:         if (isset($data['property'])) {
 70:             $this->setProperty($data['property']);
 71:         }
 72: 
 73:         if (isset($data['mode'])) {
 74:             $this->setMode($data['mode']);
 75:         }
 76: 
 77:         if (isset($data['values'])) {
 78:             $this->setValues($data['values']);
 79:         }
 80: 
 81:         if (isset($data['string'])) {
 82:             $this->setString($data['string']);
 83: 
 84:             if (!isset($data['mode'])) {
 85:                 $this->setMode(self::MODE_CUSTOM);
 86:             }
 87:         }
 88: 
 89:         if (isset($data['active'])) {
 90:             $this->setActive($data['active']);
 91:         }
 92: 
 93:         return $this;
 94:     }
 95: 
 96:     /**
 97:      * @param string $property The order property.
 98:      * @throws InvalidArgumentException If the property argument is not a string.
 99:      * @return Order (Chainable)
100:      */
101:     public function setProperty($property)
102:     {
103:         if (!is_string($property)) {
104:             throw new InvalidArgumentException(
105:                 'Order Property must be a string.'
106:             );
107:         }
108:         if ($property == '') {
109:             throw new InvalidArgumentException(
110:                 'Order Property can not be empty.'
111:             );
112:         }
113: 
114:         $this->property = $property;
115:         return $this;
116:     }
117: 
118:     /**
119:      * @return string
120:      */
121:     public function property()
122:     {
123:         return $this->property;
124:     }
125: 
126:     /**
127:      * @param string $mode The order mode.
128:      * @throws InvalidArgumentException If the mode is not a string or invalid.
129:      * @return Order Chainable
130:      */
131:     public function setMode($mode)
132:     {
133:         if (!is_string($mode)) {
134:             throw new InvalidArgumentException(
135:                 'Order Mode must be a string.'
136:             );
137:         }
138: 
139:         $mode = strtolower($mode);
140:         if (!in_array($mode, $this->validModes())) {
141:             throw new InvalidArgumentException(
142:                 sprintf('Invalid Order mode "%s".', $mode)
143:             );
144:         }
145:         $this->mode = $mode;
146:         return $this;
147:     }
148: 
149:     /**
150:      * @return string
151:      */
152:     public function mode()
153:     {
154:         return $this->mode;
155:     }
156: 
157:     /**
158:      * Set the values.
159:      * Values are ignored if the mode is not "values"
160:      *
161:      * If the `$values` argument is a string, it will be split by ",".
162:      * If it is an array, the values will be used as is.
163:      * Otherwise, the function will throw an error
164:      *
165:      * @throws InvalidArgumentException If the parameter is not an array or a string.
166:      * @param  string|array $values The order values.
167:      * @return Order (Chainable)
168:      */
169:     public function setValues($values)
170:     {
171:         if (is_string($values)) {
172:             if ($values == '') {
173:                 throw new InvalidArgumentException(
174:                     'String values can not be empty.'
175:                 );
176:             }
177:             $values = array_map('trim', explode(',', $values));
178:             $this->values = $values;
179:         } elseif (is_array($values)) {
180:             if (empty($values)) {
181:                 throw new InvalidArgumentException(
182:                     'Array values can not be empty.'
183:                 );
184:             }
185:             $this->values = $values;
186:         } else {
187:             throw new InvalidArgumentException(
188:                 'Order Values must be an array, or a comma-delimited string.'
189:             );
190:         }
191:         return $this;
192:     }
193: 
194:     /**
195:      * @return array
196:      */
197:     public function values()
198:     {
199:         return $this->values;
200:     }
201: 
202:     /**
203:      * @param  string $sql The custom order SQL string.
204:      * @throws InvalidArgumentException If the parameter is not a valid operand.
205:      * @return Order (Chainable)
206:      */
207:     public function setString($sql)
208:     {
209:         if (!is_string($sql)) {
210:             throw new InvalidArgumentException(
211:                 'Custom SQL clause should be a string.'
212:             );
213:         }
214: 
215:         $this->string = $sql;
216: 
217:         return $this;
218:     }
219: 
220:     /**
221:      * @return string
222:      */
223:     public function string()
224:     {
225:         return $this->string;
226:     }
227: 
228:     /**
229:      * @param boolean $active The active flag.
230:      * @return Order (Chainable)
231:      */
232:     public function setActive($active)
233:     {
234:         $this->active = !!$active;
235:         return $this;
236:     }
237: 
238:     /**
239:      * @return boolean
240:      */
241:     public function active()
242:     {
243:         return $this->active;
244:     }
245: 
246:     /**
247:      * Supported modes
248:      *
249:      * @return array
250:      */
251:     protected function validModes()
252:     {
253:         $validModes = [
254:             self::MODE_DESC,
255:             self::MODE_ASC,
256:             self::MODE_RANDOM,
257:             self::MODE_VALUES,
258:             self::MODE_CUSTOM
259:         ];
260: 
261:         return $validModes;
262:     }
263: }
264: