1: <?php
2:
3: namespace Alpha\Util\Search;
4:
5: /**
6: * A standard interface used for describing search engine implementations.
7: *
8: * @since 1.2.3
9: *
10: * @author John Collins <dev@alphaframework.org>
11: * @license http://www.opensource.org/licenses/bsd-license.php The BSD License
12: * @copyright Copyright (c) 2015, John Collins (founder of Alpha Framework).
13: * All rights reserved.
14: *
15: * <pre>
16: * Redistribution and use in source and binary forms, with or
17: * without modification, are permitted provided that the
18: * following conditions are met:
19: *
20: * * Redistributions of source code must retain the above
21: * copyright notice, this list of conditions and the
22: * following disclaimer.
23: * * Redistributions in binary form must reproduce the above
24: * copyright notice, this list of conditions and the
25: * following disclaimer in the documentation and/or other
26: * materials provided with the distribution.
27: * * Neither the name of the Alpha Framework nor the names
28: * of its contributors may be used to endorse or promote
29: * products derived from this software without specific
30: * prior written permission.
31: *
32: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
33: * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
34: * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
35: * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
36: * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
37: * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
38: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
39: * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
40: * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
41: * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
42: * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
43: * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
44: * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
45: * </pre>
46: */
47: interface SearchProviderInterface
48: {
49: /**
50: * The main search function, you should provide the user's search query as-is and pass it to the
51: * search engine. An array of business objects will be returned (ordered by the search engine).
52: *
53: * @param string $query The search query.
54: * @param string $returnType Use this filter to determine that only business objects of a certain class hould be returned (default is to return all classes indexed).
55: * @param int $start Start point for pagination.
56: * @param int $limit The maximum amount to return in the list (for pagination).
57: *
58: * @return array An array of matching business objects.
59: *
60: * @since 1.2.3
61: */
62: public function search($query, $returnType = 'all', $start = 0, $limit = 10);
63:
64: /**
65: * Gets a list of documents related to the business objects matching the object provided. An array
66: * of business objects will be returned (ordered by the search engine).
67: *
68: * @param Alpha\Model\ActiveRecord $sourceObject The source object for comparison.
69: * @param string $returnType Use this filter to determine that only business objects of a certain class hould be returned (default is to return all classes indexed).
70: * @param int $start Start point for pagination.
71: * @param int $limit The maximum amount to return in the list (for pagination).
72: * @param string $distinct Related items will only be returned that have distinct values in this named field.
73: *
74: * @return array An array of related business objects.
75: *
76: * @since 1.2.3
77: */
78: public function getRelated($sourceObject, $returnType = 'all', $start = 0, $limit = 10, $distinct = '');
79:
80: /**
81: * Adds/updates the business object provided to the search engine index.
82: *
83: * @param Alpha\Model\ActiveRecord $sourceObject The object to add to the search index. The sourceObject should already be stored in the database.
84: *
85: * @throws Alpha\Exception\SearchIndexWriteException
86: *
87: * @since 1.2.3
88: */
89: public function index($sourceObject);
90:
91: /**
92: * Deletes the business object provided from the search engine index.
93: *
94: * @param Alpha\Model\ActiveRecord $sourceObject The object to delete from the search index.
95: *
96: * @throws Alpha\Exception\SearchIndexWriteException
97: *
98: * @since 1.2.3
99: */
100: public function delete($sourceObject);
101:
102: /**
103: * Returns the number of matching objects found in the previous search carried out by this provider.
104: *
105: * @return int
106: *
107: * @since 1.2.3
108: */
109: public function getNumberFound();
110: }
111: