1: <?php
2: /**
3: * This file contains core interfaces for Yii framework.
4: *
5: * @author Qiang Xue <qiang.xue@gmail.com>
6: * @link http://www.yiiframework.com/
7: * @copyright 2008-2013 Yii Software LLC
8: * @license http://www.yiiframework.com/license/
9: */
10:
11: /**
12: * IApplicationComponent is the interface that all application components must implement.
13: *
14: * After the application completes configuration, it will invoke the {@link init()}
15: * method of every loaded application component.
16: *
17: * @author Qiang Xue <qiang.xue@gmail.com>
18: * @package system.base
19: * @since 1.0
20: */
21: interface IApplicationComponent
22: {
23: /**
24: * Initializes the application component.
25: * This method is invoked after the application completes configuration.
26: */
27: public function init();
28: /**
29: * @return boolean whether the {@link init()} method has been invoked.
30: */
31: public function getIsInitialized();
32: }
33:
34: /**
35: * ICache is the interface that must be implemented by cache components.
36: *
37: * This interface must be implemented by classes supporting caching feature.
38: *
39: * @author Qiang Xue <qiang.xue@gmail.com>
40: * @package system.caching
41: * @since 1.0
42: */
43: interface ICache
44: {
45: /**
46: * Retrieves a value from cache with a specified key.
47: * @param string $id a key identifying the cached value
48: * @return mixed the value stored in cache, false if the value is not in the cache or expired.
49: */
50: public function get($id);
51: /**
52: * Retrieves multiple values from cache with the specified keys.
53: * Some caches (such as memcache, apc) allow retrieving multiple cached values at one time,
54: * which may improve the performance since it reduces the communication cost.
55: * In case a cache doesn't support this feature natively, it will be simulated by this method.
56: * @param array $ids list of keys identifying the cached values
57: * @return array list of cached values corresponding to the specified keys. The array
58: * is returned in terms of (key,value) pairs.
59: * If a value is not cached or expired, the corresponding array value will be false.
60: */
61: public function mget($ids);
62: /**
63: * Stores a value identified by a key into cache.
64: * If the cache already contains such a key, the existing value and
65: * expiration time will be replaced with the new ones.
66: *
67: * @param string $id the key identifying the value to be cached
68: * @param mixed $value the value to be cached
69: * @param integer $expire the number of seconds in which the cached value will expire. 0 means never expire.
70: * @param ICacheDependency $dependency dependency of the cached item. If the dependency changes, the item is labelled invalid.
71: * @return boolean true if the value is successfully stored into cache, false otherwise
72: */
73: public function set($id,$value,$expire=0,$dependency=null);
74: /**
75: * Stores a value identified by a key into cache if the cache does not contain this key.
76: * Nothing will be done if the cache already contains the key.
77: * @param string $id the key identifying the value to be cached
78: * @param mixed $value the value to be cached
79: * @param integer $expire the number of seconds in which the cached value will expire. 0 means never expire.
80: * @param ICacheDependency $dependency dependency of the cached item. If the dependency changes, the item is labelled invalid.
81: * @return boolean true if the value is successfully stored into cache, false otherwise
82: */
83: public function add($id,$value,$expire=0,$dependency=null);
84: /**
85: * Deletes a value with the specified key from cache
86: * @param string $id the key of the value to be deleted
87: * @return boolean whether the deletion is successful
88: */
89: public function delete($id);
90: /**
91: * Deletes all values from cache.
92: * Be careful of performing this operation if the cache is shared by multiple applications.
93: * @return boolean whether the flush operation was successful.
94: */
95: public function flush();
96: }
97:
98: /**
99: * ICacheDependency is the interface that must be implemented by cache dependency classes.
100: *
101: * This interface must be implemented by classes meant to be used as
102: * cache dependencies.
103: *
104: * Objects implementing this interface must be able to be serialized and unserialized.
105: *
106: * @author Qiang Xue <qiang.xue@gmail.com>
107: * @package system.caching
108: * @since 1.0
109: */
110: interface ICacheDependency
111: {
112: /**
113: * Evaluates the dependency by generating and saving the data related with dependency.
114: * This method is invoked by cache before writing data into it.
115: */
116: public function evaluateDependency();
117: /**
118: * @return boolean whether the dependency has changed.
119: */
120: public function getHasChanged();
121: }
122:
123:
124: /**
125: * IStatePersister is the interface that must be implemented by state persister classes.
126: *
127: * This interface must be implemented by all state persister classes (such as
128: * {@link CStatePersister}.
129: *
130: * @package system.base
131: * @since 1.0
132: */
133: interface IStatePersister
134: {
135: /**
136: * Loads state data from a persistent storage.
137: * @return mixed the state
138: */
139: public function load();
140: /**
141: * Saves state data into a persistent storage.
142: * @param mixed $state the state to be saved
143: */
144: public function save($state);
145: }
146:
147:
148: /**
149: * IFilter is the interface that must be implemented by action filters.
150: *
151: * @package system.base
152: * @since 1.0
153: */
154: interface IFilter
155: {
156: /**
157: * Performs the filtering.
158: * This method should be implemented to perform actual filtering.
159: * If the filter wants to continue the action execution, it should call
160: * <code>$filterChain->run()</code>.
161: * @param CFilterChain $filterChain the filter chain that the filter is on.
162: */
163: public function filter($filterChain);
164: }
165:
166:
167: /**
168: * IAction is the interface that must be implemented by controller actions.
169: *
170: * @package system.base
171: * @since 1.0
172: */
173: interface IAction
174: {
175: /**
176: * @return string id of the action
177: */
178: public function getId();
179: /**
180: * @return CController the controller instance
181: */
182: public function getController();
183: }
184:
185:
186: /**
187: * IWebServiceProvider interface may be implemented by Web service provider classes.
188: *
189: * If this interface is implemented, the provider instance will be able
190: * to intercept the remote method invocation (e.g. for logging or authentication purpose).
191: * @author Qiang Xue <qiang.xue@gmail.com>
192: * @package system.base
193: * @since 1.0
194: */
195: interface IWebServiceProvider
196: {
197: /**
198: * This method is invoked before the requested remote method is invoked.
199: * @param CWebService $service the currently requested Web service.
200: * @return boolean whether the remote method should be executed.
201: */
202: public function beforeWebMethod($service);
203: /**
204: * This method is invoked after the requested remote method is invoked.
205: * @param CWebService $service the currently requested Web service.
206: */
207: public function afterWebMethod($service);
208: }
209:
210:
211: /**
212: * IViewRenderer interface is implemented by a view renderer class.
213: *
214: * A view renderer is {@link CWebApplication::viewRenderer viewRenderer}
215: * application component whose wants to replace the default view rendering logic
216: * implemented in {@link CBaseController}.
217: *
218: * @author Qiang Xue <qiang.xue@gmail.com>
219: * @package system.base
220: * @since 1.0
221: */
222: interface IViewRenderer
223: {
224: /**
225: * Renders a view file.
226: * @param CBaseController $context the controller or widget who is rendering the view file.
227: * @param string $file the view file path
228: * @param mixed $data the data to be passed to the view
229: * @param boolean $return whether the rendering result should be returned
230: * @return mixed the rendering result, or null if the rendering result is not needed.
231: */
232: public function renderFile($context,$file,$data,$return);
233: }
234:
235:
236: /**
237: * IUserIdentity interface is implemented by a user identity class.
238: *
239: * An identity represents a way to authenticate a user and retrieve
240: * information needed to uniquely identity the user. It is normally
241: * used with the {@link CWebApplication::user user application component}.
242: *
243: * @author Qiang Xue <qiang.xue@gmail.com>
244: * @package system.base
245: * @since 1.0
246: */
247: interface IUserIdentity
248: {
249: /**
250: * Authenticates the user.
251: * The information needed to authenticate the user
252: * are usually provided in the constructor.
253: * @return boolean whether authentication succeeds.
254: */
255: public function authenticate();
256: /**
257: * Returns a value indicating whether the identity is authenticated.
258: * @return boolean whether the identity is valid.
259: */
260: public function getIsAuthenticated();
261: /**
262: * Returns a value that uniquely represents the identity.
263: * @return mixed a value that uniquely represents the identity (e.g. primary key value).
264: */
265: public function getId();
266: /**
267: * Returns the display name for the identity (e.g. username).
268: * @return string the display name for the identity.
269: */
270: public function getName();
271: /**
272: * Returns the additional identity information that needs to be persistent during the user session.
273: * @return array additional identity information that needs to be persistent during the user session (excluding {@link id}).
274: */
275: public function getPersistentStates();
276: }
277:
278:
279: /**
280: * IWebUser interface is implemented by a {@link CWebApplication::user user application component}.
281: *
282: * A user application component represents the identity information
283: * for the current user.
284: *
285: * @author Qiang Xue <qiang.xue@gmail.com>
286: * @package system.base
287: * @since 1.0
288: */
289: interface IWebUser
290: {
291: /**
292: * Returns a value that uniquely represents the identity.
293: * @return mixed a value that uniquely represents the identity (e.g. primary key value).
294: */
295: public function getId();
296: /**
297: * Returns the display name for the identity (e.g. username).
298: * @return string the display name for the identity.
299: */
300: public function getName();
301: /**
302: * Returns a value indicating whether the user is a guest (not authenticated).
303: * @return boolean whether the user is a guest (not authenticated)
304: */
305: public function getIsGuest();
306: /**
307: * Performs access check for this user.
308: * @param string $operation the name of the operation that need access check.
309: * @param array $params name-value pairs that would be passed to business rules associated
310: * with the tasks and roles assigned to the user.
311: * @return boolean whether the operations can be performed by this user.
312: */
313: public function checkAccess($operation,$params=array());
314: /**
315: * Redirects the user browser to the login page.
316: * Before the redirection, the current URL (if it's not an AJAX url) will be
317: * kept in {@link returnUrl} so that the user browser may be redirected back
318: * to the current page after successful login. Make sure you set {@link loginUrl}
319: * so that the user browser can be redirected to the specified login URL after
320: * calling this method.
321: * After calling this method, the current request processing will be terminated.
322: */
323: public function loginRequired();
324: }
325:
326:
327: /**
328: * IAuthManager interface is implemented by an auth manager application component.
329: *
330: * An auth manager is mainly responsible for providing role-based access control (RBAC) service.
331: *
332: * @author Qiang Xue <qiang.xue@gmail.com>
333: * @package system.base
334: * @since 1.0
335: */
336: interface IAuthManager
337: {
338: /**
339: * Performs access check for the specified user.
340: * @param string $itemName the name of the operation that we are checking access to
341: * @param mixed $userId the user ID. This should be either an integer or a string representing
342: * the unique identifier of a user. See {@link IWebUser::getId}.
343: * @param array $params name-value pairs that would be passed to biz rules associated
344: * with the tasks and roles assigned to the user.
345: * @return boolean whether the operations can be performed by the user.
346: */
347: public function checkAccess($itemName,$userId,$params=array());
348:
349: /**
350: * Creates an authorization item.
351: * An authorization item represents an action permission (e.g. creating a post).
352: * It has three types: operation, task and role.
353: * Authorization items form a hierarchy. Higher level items inherit permissions representing
354: * by lower level items.
355: * @param string $name the item name. This must be a unique identifier.
356: * @param integer $type the item type (0: operation, 1: task, 2: role).
357: * @param string $description description of the item
358: * @param string $bizRule business rule associated with the item. This is a piece of
359: * PHP code that will be executed when {@link checkAccess} is called for the item.
360: * @param mixed $data additional data associated with the item.
361: * @return CAuthItem the authorization item
362: * @throws CException if an item with the same name already exists
363: */
364: public function createAuthItem($name,$type,$description='',$bizRule=null,$data=null);
365: /**
366: * Removes the specified authorization item.
367: * @param string $name the name of the item to be removed
368: * @return boolean whether the item exists in the storage and has been removed
369: */
370: public function removeAuthItem($name);
371: /**
372: * Returns the authorization items of the specific type and user.
373: * @param integer $type the item type (0: operation, 1: task, 2: role). Defaults to null,
374: * meaning returning all items regardless of their type.
375: * @param mixed $userId the user ID. Defaults to null, meaning returning all items even if
376: * they are not assigned to a user.
377: * @return array the authorization items of the specific type.
378: */
379: public function getAuthItems($type=null,$userId=null);
380: /**
381: * Returns the authorization item with the specified name.
382: * @param string $name the name of the item
383: * @return CAuthItem the authorization item. Null if the item cannot be found.
384: */
385: public function getAuthItem($name);
386: /**
387: * Saves an authorization item to persistent storage.
388: * @param CAuthItem $item the item to be saved.
389: * @param string $oldName the old item name. If null, it means the item name is not changed.
390: */
391: public function saveAuthItem($item,$oldName=null);
392:
393: /**
394: * Adds an item as a child of another item.
395: * @param string $itemName the parent item name
396: * @param string $childName the child item name
397: * @throws CException if either parent or child doesn't exist or if a loop has been detected.
398: */
399: public function addItemChild($itemName,$childName);
400: /**
401: * Removes a child from its parent.
402: * Note, the child item is not deleted. Only the parent-child relationship is removed.
403: * @param string $itemName the parent item name
404: * @param string $childName the child item name
405: * @return boolean whether the removal is successful
406: */
407: public function removeItemChild($itemName,$childName);
408: /**
409: * Returns a value indicating whether a child exists within a parent.
410: * @param string $itemName the parent item name
411: * @param string $childName the child item name
412: * @return boolean whether the child exists
413: */
414: public function hasItemChild($itemName,$childName);
415: /**
416: * Returns the children of the specified item.
417: * @param mixed $itemName the parent item name. This can be either a string or an array.
418: * The latter represents a list of item names.
419: * @return array all child items of the parent
420: */
421: public function getItemChildren($itemName);
422:
423: /**
424: * Assigns an authorization item to a user.
425: * @param string $itemName the item name
426: * @param mixed $userId the user ID (see {@link IWebUser::getId})
427: * @param string $bizRule the business rule to be executed when {@link checkAccess} is called
428: * for this particular authorization item.
429: * @param mixed $data additional data associated with this assignment
430: * @return CAuthAssignment the authorization assignment information.
431: * @throws CException if the item does not exist or if the item has already been assigned to the user
432: */
433: public function assign($itemName,$userId,$bizRule=null,$data=null);
434: /**
435: * Revokes an authorization assignment from a user.
436: * @param string $itemName the item name
437: * @param mixed $userId the user ID (see {@link IWebUser::getId})
438: * @return boolean whether removal is successful
439: */
440: public function revoke($itemName,$userId);
441: /**
442: * Returns a value indicating whether the item has been assigned to the user.
443: * @param string $itemName the item name
444: * @param mixed $userId the user ID (see {@link IWebUser::getId})
445: * @return boolean whether the item has been assigned to the user.
446: */
447: public function isAssigned($itemName,$userId);
448: /**
449: * Returns the item assignment information.
450: * @param string $itemName the item name
451: * @param mixed $userId the user ID (see {@link IWebUser::getId})
452: * @return CAuthAssignment the item assignment information. Null is returned if
453: * the item is not assigned to the user.
454: */
455: public function getAuthAssignment($itemName,$userId);
456: /**
457: * Returns the item assignments for the specified user.
458: * @param mixed $userId the user ID (see {@link IWebUser::getId})
459: * @return array the item assignment information for the user. An empty array will be
460: * returned if there is no item assigned to the user.
461: */
462: public function getAuthAssignments($userId);
463: /**
464: * Saves the changes to an authorization assignment.
465: * @param CAuthAssignment $assignment the assignment that has been changed.
466: */
467: public function saveAuthAssignment($assignment);
468:
469: /**
470: * Removes all authorization data.
471: */
472: public function clearAll();
473: /**
474: * Removes all authorization assignments.
475: */
476: public function clearAuthAssignments();
477:
478: /**
479: * Saves authorization data into persistent storage.
480: * If any change is made to the authorization data, please make
481: * sure you call this method to save the changed data into persistent storage.
482: */
483: public function save();
484:
485: /**
486: * Executes a business rule.
487: * A business rule is a piece of PHP code that will be executed when {@link checkAccess} is called.
488: * @param string $bizRule the business rule to be executed.
489: * @param array $params additional parameters to be passed to the business rule when being executed.
490: * @param mixed $data additional data that is associated with the corresponding authorization item or assignment
491: * @return boolean whether the execution returns a true value.
492: * If the business rule is empty, it will also return true.
493: */
494: public function executeBizRule($bizRule,$params,$data);
495: }
496:
497:
498: /**
499: * IBehavior interfaces is implemented by all behavior classes.
500: *
501: * A behavior is a way to enhance a component with additional methods that
502: * are defined in the behavior class and not available in the component class.
503: *
504: * @author Qiang Xue <qiang.xue@gmail.com>
505: * @package system.base
506: */
507: interface IBehavior
508: {
509: /**
510: * Attaches the behavior object to the component.
511: * @param CComponent $component the component that this behavior is to be attached to.
512: */
513: public function attach($component);
514: /**
515: * Detaches the behavior object from the component.
516: * @param CComponent $component the component that this behavior is to be detached from.
517: */
518: public function detach($component);
519: /**
520: * @return boolean whether this behavior is enabled
521: */
522: public function getEnabled();
523: /**
524: * @param boolean $value whether this behavior is enabled
525: */
526: public function setEnabled($value);
527: }
528:
529: /**
530: * IWidgetFactory is the interface that must be implemented by a widget factory class.
531: *
532: * When calling {@link CBaseController::createWidget}, if a widget factory is available,
533: * it will be used for creating the requested widget.
534: *
535: * @author Qiang Xue <qiang.xue@gmail.com>
536: * @package system.web
537: * @since 1.1
538: */
539: interface IWidgetFactory
540: {
541: /**
542: * Creates a new widget based on the given class name and initial properties.
543: * @param CBaseController $owner the owner of the new widget
544: * @param string $className the class name of the widget. This can also be a path alias (e.g. system.web.widgets.COutputCache)
545: * @param array $properties the initial property values (name=>value) of the widget.
546: * @return CWidget the newly created widget whose properties have been initialized with the given values.
547: */
548: public function createWidget($owner,$className,$properties=array());
549: }
550:
551: /**
552: * IDataProvider is the interface that must be implemented by data provider classes.
553: *
554: * Data providers are components that can feed data for widgets such as data grid, data list.
555: * Besides providing data, they also support pagination and sorting.
556: *
557: * @author Qiang Xue <qiang.xue@gmail.com>
558: * @package system.web
559: * @since 1.1
560: */
561: interface IDataProvider
562: {
563: /**
564: * @return string the unique ID that identifies the data provider from other data providers.
565: */
566: public function getId();
567: /**
568: * Returns the number of data items in the current page.
569: * This is equivalent to <code>count($provider->getData())</code>.
570: * When {@link pagination} is set false, this returns the same value as {@link totalItemCount}.
571: * @param boolean $refresh whether the number of data items should be re-calculated.
572: * @return integer the number of data items in the current page.
573: */
574: public function getItemCount($refresh=false);
575: /**
576: * Returns the total number of data items.
577: * When {@link pagination} is set false, this returns the same value as {@link itemCount}.
578: * @param boolean $refresh whether the total number of data items should be re-calculated.
579: * @return integer total number of possible data items.
580: */
581: public function getTotalItemCount($refresh=false);
582: /**
583: * Returns the data items currently available.
584: * @param boolean $refresh whether the data should be re-fetched from persistent storage.
585: * @return array the list of data items currently available in this data provider.
586: */
587: public function getData($refresh=false);
588: /**
589: * Returns the key values associated with the data items.
590: * @param boolean $refresh whether the keys should be re-calculated.
591: * @return array the list of key values corresponding to {@link data}. Each data item in {@link data}
592: * is uniquely identified by the corresponding key value in this array.
593: */
594: public function getKeys($refresh=false);
595: /**
596: * @return CSort the sorting object. If this is false, it means the sorting is disabled.
597: */
598: public function getSort();
599: /**
600: * @return CPagination the pagination object. If this is false, it means the pagination is disabled.
601: */
602: public function getPagination();
603: }
604:
605:
606: /**
607: * ILogFilter is the interface that must be implemented by log filters.
608: *
609: * A log filter preprocesses the logged messages before they are handled by a log route.
610: * You can attach classes that implement ILogFilter to {@link CLogRoute::$filter}.
611: *
612: * @package system.logging
613: * @since 1.1.11
614: */
615: interface ILogFilter
616: {
617: /**
618: * This method should be implemented to perform actual filtering of log messages
619: * by working on the array given as the first parameter.
620: * Implementation might reformat, remove or add information to logged messages.
621: * @param array $logs list of messages. Each array element represents one message
622: * with the following structure:
623: * array(
624: * [0] => message (string)
625: * [1] => level (string)
626: * [2] => category (string)
627: * [3] => timestamp (float, obtained by microtime(true));
628: */
629: public function filter(&$logs);
630: }
631:
632: