From 69471d36b20f94d0d24f81fdb30b817e5645648b Mon Sep 17 00:00:00 2001 From: Simon Date: Mon, 9 Sep 2019 12:38:46 +1200 Subject: [PATCH] Look ma! I'm writing docs! --- src/Factories/QueryComponentFactory.php | 9 ++++ src/Helpers/DataResolver.php | 2 +- src/Helpers/SolrLogger.php | 5 ++- src/Indexes/BaseIndex.php | 20 ++++++++- src/Jobs/SolrConfigureJob.php | 4 +- src/Jobs/SolrIndexJob.php | 20 ++++++++- src/Results/SearchResult.php | 42 +++++++++++++++++-- src/Services/SchemaService.php | 28 +++++++++++-- src/States/SiteState.php | 2 +- src/Tasks/SolrIndexTask.php | 25 ++++++++++- .../DataResolverTraits/DataResolveTrait.php | 10 +++++ src/Traits/LoggerTrait.php | 6 +++ .../QueryComponentBoostTrait.php | 11 ++++- .../GetSetSchemaServiceTrait.php | 32 ++++++++++++-- 14 files changed, 197 insertions(+), 19 deletions(-) diff --git a/src/Factories/QueryComponentFactory.php b/src/Factories/QueryComponentFactory.php index 21049a55..eea4d450 100644 --- a/src/Factories/QueryComponentFactory.php +++ b/src/Factories/QueryComponentFactory.php @@ -52,18 +52,25 @@ class QueryComponentFactory 'Spellcheck', ]; /** + * BaseQuery that needs to be executed * @var BaseQuery */ protected $query; /** + * Helper to escape the query terms properly + * * @var Helper */ protected $helper; /** + * Resulting querie parts as an array + * * @var array */ protected $queryArray = []; /** + * Index to query + * * @var BaseIndex */ protected $index; @@ -156,6 +163,8 @@ public function getClientQuery(): Query } /** + * Set a custom Client Query object + * * @param Query $clientQuery * @return self */ diff --git a/src/Helpers/DataResolver.php b/src/Helpers/DataResolver.php index 9f6acd5e..9e752bef 100644 --- a/src/Helpers/DataResolver.php +++ b/src/Helpers/DataResolver.php @@ -60,7 +60,7 @@ public function __construct($component, $columns = []) */ public static function identify($obj, $columns = []) { - /** @var @see {self::$objTypes} $type */ + /** @var {@link self::$objTypes} $type */ foreach (self::$objTypes as $type => $method) { if ($obj instanceof $type) { $method = 'resolve' . $method; diff --git a/src/Helpers/SolrLogger.php b/src/Helpers/SolrLogger.php index 40fdf321..69f3d831 100644 --- a/src/Helpers/SolrLogger.php +++ b/src/Helpers/SolrLogger.php @@ -16,11 +16,14 @@ * * Log information from Solr to the CMS for reference * + * @todo implement {@link LoggerInterface} * @package Firesphere\SolrSearch\Helpers */ class SolrLogger { /** + * Guzzle base client to communicate with Solr + * * @var Client */ protected $client; @@ -54,7 +57,7 @@ public function __construct($handler = null) * @throws GuzzleException * @throws ValidationException */ - public static function logMessage($type, $message, $index) + public static function logMessage($type, $message, $index): void { $solrLogger = new self(); $solrLogger->saveSolrLog($type); diff --git a/src/Indexes/BaseIndex.php b/src/Indexes/BaseIndex.php index 332f6001..41eeb1cf 100644 --- a/src/Indexes/BaseIndex.php +++ b/src/Indexes/BaseIndex.php @@ -69,14 +69,20 @@ abstract class BaseIndex 'StoredFields', ]; /** - * @var \Solarium\Core\Query\Result\Result + * The raw query result + * + * @var Result */ protected $rawQuery; /** + * {@link SchemaService} + * * @var SchemaService */ protected $schemaService; /** + * {@link QueryComponentFactory} + * * @var QueryComponentFactory */ protected $queryFactory; @@ -87,6 +93,8 @@ abstract class BaseIndex */ protected $queryTerms = []; /** + * Should a retry occur if nothing was found and there are suggestions to follow + * * @var bool */ private $retry = false; @@ -224,6 +232,8 @@ public function doSearch(BaseQuery $query) } /** + * From the given BaseQuery, generate a Solarium ClientQuery object + * * @param BaseQuery $query * @return Query */ @@ -242,6 +252,8 @@ public function buildSolrQuery(BaseQuery $query): Query } /** + * Build a factory to use in the SolrQuery building. {@link static::buildSolrQuery()} + * * @param BaseQuery $query * @param Query $clientQuery * @return QueryComponentFactory|mixed @@ -304,6 +316,8 @@ protected function spellcheckRetry(BaseQuery $query, SearchResult $searchResult) } /** + * Get all fields that are required for indexing in a unique way + * * @return array */ public function getFieldsForIndexing(): array @@ -381,6 +395,8 @@ public function getSynonyms($defaults = true): string } /** + * Get the final, generated terms + * * @return array */ public function getQueryTerms(): array @@ -389,6 +405,8 @@ public function getQueryTerms(): array } /** + * Get the QueryComponentFactory. {@link QueryComponentFactory} + * * @return QueryComponentFactory */ public function getQueryFactory(): QueryComponentFactory diff --git a/src/Jobs/SolrConfigureJob.php b/src/Jobs/SolrConfigureJob.php index f388da16..d4956ae9 100644 --- a/src/Jobs/SolrConfigureJob.php +++ b/src/Jobs/SolrConfigureJob.php @@ -20,6 +20,8 @@ class SolrConfigureJob extends AbstractQueuedJob { /** + * My name + * * @return string */ public function getTitle(): string @@ -28,7 +30,7 @@ public function getTitle(): string } /** - * Do some processing yourself! + * Process the queue for indexes that need to be indexed properly * * @return void * @throws ReflectionException diff --git a/src/Jobs/SolrIndexJob.php b/src/Jobs/SolrIndexJob.php index be0f25a5..823c2169 100644 --- a/src/Jobs/SolrIndexJob.php +++ b/src/Jobs/SolrIndexJob.php @@ -15,7 +15,9 @@ use Symbiote\QueuedJobs\Services\QueuedJobService; /** - * Class SolrIndexJob + * Class SolrIndexJob is a queued job to index all existing indexes and their classes. + * + * It always runs on all indexes, to make sure all indexes are up to date. * * @package Firesphere\SolrSearch\Jobs */ @@ -42,6 +44,8 @@ class SolrIndexJob extends AbstractQueuedJob protected $indexes; /** + * My name + * * @return string */ public function getTitle() @@ -50,7 +54,7 @@ public function getTitle() } /** - * Do some processing yourself! + * Process this job * * @return self * @throws Exception @@ -89,6 +93,8 @@ public function process() } /** + * Configure the run for the valid indexes + * * @param stdClass|null $data * @throws ReflectionException */ @@ -130,6 +136,8 @@ public function afterComplete() } /** + * Get the next step to execute + * * @return array */ protected function getNextSteps(): array @@ -155,6 +163,8 @@ protected function getNextSteps(): array } /** + * Which Indexes should I index + * * @return array */ public function getClassToIndex(): array @@ -163,6 +173,8 @@ public function getClassToIndex(): array } /** + * Which classes should I index + * * @param array $classToIndex * @return SolrIndexJob */ @@ -174,6 +186,8 @@ public function setClassToIndex($classToIndex) } /** + * Get the indexes + * * @return array */ public function getIndexes(): array @@ -182,6 +196,8 @@ public function getIndexes(): array } /** + * Set the indexes if needed + * * @param array $indexes * @return SolrIndexJob */ diff --git a/src/Results/SearchResult.php b/src/Results/SearchResult.php index e27b5e9e..385b06b8 100644 --- a/src/Results/SearchResult.php +++ b/src/Results/SearchResult.php @@ -10,6 +10,7 @@ use Firesphere\SolrSearch\Traits\SearchResultSetTrait; use SilverStripe\Control\HTTPRequest; use SilverStripe\ORM\ArrayList; +use SilverStripe\ORM\DataList; use SilverStripe\ORM\DataObject; use SilverStripe\ORM\FieldType\DBField; use SilverStripe\ORM\PaginatedList; @@ -20,9 +21,13 @@ use Solarium\Component\Result\Spellcheck\Result as SpellcheckResult; use Solarium\QueryType\Select\Result\Document; use Solarium\QueryType\Select\Result\Result; +use stdClass; /** - * Class SearchResult + * Class SearchResult is the combined result in a SilverStripe readable way + * + * Each of the requested features of a BaseQuery are generated to be easily accessible in the controller. + * In the controller, each required item can be accessed through the resulting method in this class. * * @package Firesphere\SolrSearch\Results */ @@ -31,17 +36,23 @@ class SearchResult use SearchResultGetTrait; use SearchResultSetTrait; /** + * Query that has been executed + * * @var BaseQuery */ protected $query; /** + * Index the query has run on + * * @var BaseIndex */ protected $index; /** - * @var ArrayList + * Resulting matches from the query on the index + * + * @var stdClass|ArrayList|DataList|DataObject */ protected $matches; @@ -69,6 +80,8 @@ public function __construct(Result $result, BaseQuery $query, BaseIndex $index) } /** + * Set the facets to build + * * @param FacetSet|null $facets * @return $this */ @@ -101,6 +114,8 @@ protected function buildFacets($facets): ArrayData } /** + * Create facets from each faceted class + * * @param FacetSet $facets * @param array $options * @param string $class @@ -125,6 +140,8 @@ protected function createFacet($facets, $options, $class, array $facetArray): ar } /** + * Get the facets for each class and their count + * * @param $class * @param array $values * @param ArrayList $results @@ -142,6 +159,8 @@ protected function getClassFacets($class, array $values, &$results): void } /** + * Set the collated spellcheck string + * * @param mixed $collatedSpellcheck * @return $this */ @@ -156,6 +175,8 @@ public function setCollatedSpellcheck($collatedSpellcheck): self } /** + * Set the spellcheck list as an ArrayList + * * @param SpellcheckResult|null $spellcheck * @return SearchResult */ @@ -175,6 +196,8 @@ public function setSpellcheck($spellcheck): self } /** + * Get the matches as a Paginated List + * * @param HTTPRequest $request * @return PaginatedList */ @@ -197,6 +220,9 @@ public function getPaginatedMatches(HTTPRequest $request): PaginatedList } /** + * Get the matches as an ArrayList and add an excerpt if possible. + * {@link static::createExcerpt()} + * * @return ArrayList */ public function getMatches(): ArrayList @@ -219,6 +245,8 @@ public function getMatches(): ArrayList } /** + * Set the matches from Solarium as an ArrayList + * * @param array $result * @return $this */ @@ -237,6 +265,8 @@ protected function setMatches($result): self } /** + * Check if the match is a DataObject and exists + * * @param $match * @param string $classIDField * @return DataObject|bool @@ -253,6 +283,8 @@ protected function isDataObject($match, string $classIDField) } /** + * Generate an excerpt for a DataObject + * * @param string $idField * @param $match * @param DataObject $item @@ -270,6 +302,8 @@ protected function createExcerpt(string $idField, $match, DataObject $item): voi } /** + * Get the highlight for a specific document + * * @param $docID * @return string */ @@ -287,9 +321,9 @@ public function getHighlightByID($docID): string } /** - * Allow overriding of matches with a custom result + * Allow overriding of matches with a custom result. Accepts anything you like, mostly * - * @param $matches + * @param stdClass|ArrayList|DataList|DataObject $matches * @return mixed */ public function setCustomisedMatches($matches) diff --git a/src/Services/SchemaService.php b/src/Services/SchemaService.php index d1398d2c..034877ba 100644 --- a/src/Services/SchemaService.php +++ b/src/Services/SchemaService.php @@ -24,11 +24,15 @@ class SchemaService extends ViewableData use GetSetSchemaServiceTrait; /** + * The field resolver to find a field for a class + * * @var FieldResolver */ - protected $introspection; + protected $fieldResolver; /** + * CoreService to use + * * @var SolrCoreService */ protected $coreService; @@ -39,11 +43,13 @@ class SchemaService extends ViewableData public function __construct() { parent::__construct(); - $this->introspection = Injector::inst()->get(FieldResolver::class); + $this->fieldResolver = Injector::inst()->get(FieldResolver::class); $this->coreService = Injector::inst()->get(SolrCoreService::class); } /** + * Get all fulltext field definitions that are loaded + * * @return ArrayList * @throws Exception */ @@ -64,6 +70,8 @@ public function getFulltextFieldDefinitions() } /** + * Get the field definition for a single field + * * @param $fieldName * @param ArrayList $return * @param null|string $copyField @@ -71,7 +79,7 @@ public function getFulltextFieldDefinitions() */ protected function getFieldDefinition($fieldName, &$return, $copyField = null) { - $field = $this->introspection->resolveField($fieldName); + $field = $this->fieldResolver->resolveField($fieldName); $typeMap = Statics::getTypeMap(); $storeFields = $this->getStoreFields(); $item = []; @@ -95,6 +103,8 @@ protected function getFieldDefinition($fieldName, &$return, $copyField = null) } /** + * Get the stored fields. This includes boosted and faceted fields + * * @return array */ protected function getStoreFields(): array @@ -113,6 +123,8 @@ protected function getStoreFields(): array } /** + * Get the fields that should be copied + * * @return ArrayList */ public function getCopyFields() @@ -134,6 +146,8 @@ public function getCopyFields() } /** + * Get the definition of a copy field for determining what to load in to Solr + * * @return ArrayList * @throws Exception */ @@ -158,6 +172,8 @@ public function getCopyFieldDefinitions() } /** + * Get the definitions of a filter field to load in to Solr. + * * @return ArrayList * @throws Exception */ @@ -182,6 +198,8 @@ public function getFilterFieldDefinitions() } /** + * Get the types template in a rendered state + * * @return DBHTMLText */ public function getTypes() @@ -197,6 +215,8 @@ public function getTypes() } /** + * Generate the Schema xml + * * @return DBHTMLText */ public function generateSchema() @@ -212,6 +232,8 @@ public function generateSchema() } /** + * Get any extras that need loading in to Solr + * * @return string */ public function getExtrasPath() diff --git a/src/States/SiteState.php b/src/States/SiteState.php index 347de212..9587ef5c 100644 --- a/src/States/SiteState.php +++ b/src/States/SiteState.php @@ -22,7 +22,7 @@ * "States" set the state of the site to a required setting for each available state. * * States SHOULD add their own states through an extension, otherwise it won't be called. - * {@see FluentExtension::onBeforeInit()} + * {@link FluentExtension::onBeforeInit()} * * States, options, etc. are simplified for a more streamlined approach * diff --git a/src/Tasks/SolrIndexTask.php b/src/Tasks/SolrIndexTask.php index 95c316aa..1f609484 100644 --- a/src/Tasks/SolrIndexTask.php +++ b/src/Tasks/SolrIndexTask.php @@ -33,26 +33,32 @@ class SolrIndexTask extends BuildTask { use LoggerTrait; /** + * URLSegment of this task * @var string */ private static $segment = 'SolrIndexTask'; /** - * @var array Store the current states for all instances of SiteState + * Store the current states for all instances of SiteState + * @var array */ public $currentStates; /** + * My name * @var string */ protected $title = 'Solr Index update'; /** + * What do I do? * @var string */ protected $description = 'Add or update documents to an existing Solr core.'; /** + * Debug mode enabled, default false * @var bool */ protected $debug = false; /** + * Singleton of {@link SolrCoreService} * @var SolrCoreService */ protected $service; @@ -75,6 +81,8 @@ public function __construct() } /** + * Set the {@link SolrCoreService} + * * @param SolrCoreService $service * @return SolrIndexTask */ @@ -86,6 +94,8 @@ public function setService(SolrCoreService $service): SolrIndexTask } /** + * Set the debug mode + * * @param bool $debug * @return SolrIndexTask */ @@ -138,6 +148,8 @@ public function run($request) } /** + * Set up the requirements for this task + * * @param HTTPRequest $request * @return array */ @@ -154,6 +166,8 @@ protected function taskSetup($request): array } /** + * get the classes to run for this task execution + * * @param $vars * @param array $classes * @return bool|array @@ -183,6 +197,8 @@ public function clearIndex($vars, BaseIndex $index) } /** + * Index the classes for a specific index + * * @param $classes * @param $isGroup * @param BaseIndex $index @@ -202,6 +218,8 @@ protected function indexClassForIndex($classes, $isGroup, BaseIndex $index, $gro } /** + * Index a single class for a given index. {@link static::indexClassForIndex()} + * * @param bool $isGroup * @param string $class * @param BaseIndex $index @@ -257,6 +275,8 @@ private function doReindex($group, $class, $batchLength, BaseIndex $index): void } /** + * Index a group of a class for a specific state and index + * * @param $group * @param $class * @param $batchLength @@ -294,6 +314,9 @@ private function updateIndex(BaseIndex $index, $items): void } /** + * Log an exception if it happens. Most are catched, these logs are for the developers + * to identify problems and fix them. + * * @param string $index * @param int $group * @param Exception $exception diff --git a/src/Traits/DataResolverTraits/DataResolveTrait.php b/src/Traits/DataResolverTraits/DataResolveTrait.php index 5e53de9a..ddce2307 100644 --- a/src/Traits/DataResolverTraits/DataResolveTrait.php +++ b/src/Traits/DataResolverTraits/DataResolveTrait.php @@ -17,18 +17,22 @@ trait DataResolveTrait { /** + * Component to resolve * @var DataObject|ArrayList|SS_List|DBField */ protected $component; /** + * Columns to resolve * @var array */ protected $columns = []; /** + * Column to resolve * @var mixed|string|null */ protected $columnName = ''; /** + * ShortName of a class * @var string */ protected $shortName; @@ -52,6 +56,8 @@ protected function resolveArrayData() } /** + * Each class using this trait should have a way to throw unidentifiable objects or items + * * @param DataObject|ArrayData|SS_List $component * @param array $columns * @@ -132,6 +138,8 @@ protected function resolveDataObject() } /** + * Get the value for a method + * * @return mixed */ protected function getMethodValue() @@ -146,6 +154,8 @@ protected function getMethodValue() } /** + * Get the value for a field + * * @return mixed */ protected function getFieldValue() diff --git a/src/Traits/LoggerTrait.php b/src/Traits/LoggerTrait.php index 79e75296..c86af4a7 100644 --- a/src/Traits/LoggerTrait.php +++ b/src/Traits/LoggerTrait.php @@ -14,11 +14,15 @@ trait LoggerTrait { /** + * The logger to use + * * @var LoggerInterface */ protected $logger; /** + * Get the logger + * * @return LoggerInterface */ public function getLogger() @@ -31,6 +35,8 @@ public function getLogger() } /** + * Set the logger if needed + * * @param LoggerInterface $logger */ public function setLogger($logger): void diff --git a/src/Traits/QueryComponentTraits/QueryComponentBoostTrait.php b/src/Traits/QueryComponentTraits/QueryComponentBoostTrait.php index f50e0efd..cbb47504 100644 --- a/src/Traits/QueryComponentTraits/QueryComponentBoostTrait.php +++ b/src/Traits/QueryComponentTraits/QueryComponentBoostTrait.php @@ -8,26 +8,31 @@ use Minimalcode\Search\Criteria; /** - * Trait QueryComponentBoostTrait + * Trait QueryComponentBoostTrait adds support for boosting to a QueryComponent * * @package Firesphere\SolrSearch\Traits */ trait QueryComponentBoostTrait { /** + * BaseQuery that is going to be executed * @var BaseQuery */ protected $query; /** + * Terms that are going to be boosted * @var array */ protected $boostTerms = []; /** + * Query set that has been executed * @var array */ protected $queryArray = []; /** + * Get the boosted terms + * * @return array */ public function getBoostTerms(): array @@ -36,6 +41,8 @@ public function getBoostTerms(): array } /** + * Set the boosted terms manually + * * @param array $boostTerms * @return QueryComponentFactory */ @@ -47,6 +54,8 @@ public function setBoostTerms(array $boostTerms): self } /** + * Build the boosted field setup through Criteria + * * Add the index-time boosting to the query */ protected function buildBoosts(): void diff --git a/src/Traits/SchemaServiceTraits/GetSetSchemaServiceTrait.php b/src/Traits/SchemaServiceTraits/GetSetSchemaServiceTrait.php index 7dd26204..4bd51b9b 100644 --- a/src/Traits/SchemaServiceTraits/GetSetSchemaServiceTrait.php +++ b/src/Traits/SchemaServiceTraits/GetSetSchemaServiceTrait.php @@ -15,23 +15,33 @@ trait GetSetSchemaServiceTrait { /** - * @var string ABSOLUTE Path to template + * ABSOLUTE Path to template + * + * @var string */ protected $template; /** + * Store the value in Solr + * * @var bool */ protected $store = false; /** + * Index to generate the schema for + * * @var BaseIndex */ protected $index; /** - * @var string ABSOLUTE Path to types.ss template + * ABSOLUTE Path to types.ss template + * + * @var string */ protected $typesTemplate; /** + * Set the store value + * * @param bool $store */ public function setStore(bool $store): void @@ -40,6 +50,8 @@ public function setStore(bool $store): void } /** + * Get the Index that's being used + * * @return BaseIndex */ public function getIndex() @@ -48,6 +60,8 @@ public function getIndex() } /** + * Set the index that's being used and add the introspection for it + * * @param BaseIndex $index * @return SchemaService */ @@ -56,12 +70,14 @@ public function setIndex($index): self $this->index = $index; // Add the index to the introspection as well, there's no need for a separate call here // We're loading this core, why would we want the introspection from a different index? - $this->introspection->setIndex($index); + $this->fieldResolver->setIndex($index); return $this; } /** + * Get the name of the index being used + * * @return string */ public function getIndexName(): string @@ -70,6 +86,8 @@ public function getIndexName(): string } /** + * Get the default field to generate df components for + * * @return string|array */ public function getDefaultField() @@ -98,6 +116,8 @@ public function getClassID(): string } /** + * Get the types template if defined + * * @return string */ public function getTypesTemplate() @@ -106,6 +126,8 @@ public function getTypesTemplate() } /** + * Set custom types template + * * @param string $typesTemplate * @return SchemaService */ @@ -117,6 +139,8 @@ public function setTypesTemplate($typesTemplate): self } /** + * Get the base template for the schema xml + * * @return string */ public function getTemplate() @@ -125,6 +149,8 @@ public function getTemplate() } /** + * Set a custom template for schema xml + * * @param string $template * @return SchemaService */