sfPropelZSLSearchPlugin
0.0.1alpha
for sf 1.4sf 1.3sf 1.2sf 1.1sf 1.0 and Propel
MIT
This plugin still needs to be claimed by its lead developer.
If you are the lead developer of this plugin, please send an email to fabien.potencier [[at]] symfony-project.com with your username.
Developers
License
--------------------------------------------------------------------------------
sfPropelZSLSearch Plugin
--------------------------------------------------------------------------------
Copyright (c) 2007 Carl Vondrick
Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
--------------------------------------------------------------------------------
Zend Search Lucene
--------------------------------------------------------------------------------
Copyright (c) 2005-2007, Zend Technologies USA, Inc.
All rights reserved.
Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
* Neither the name of Zend Technologies USA, Inc. nor the names of its
contributors may be used to endorse or promote products derived from this
software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Introduction
sfPropelZSLSearchPlugin integrates symfony, Propel, and Zend Search Lucene together to easily add a site search functionality to your application. It allows for documents to be created off models generated by Propel (a Doctrine port is probably possible too) and also for documents to be created off actions. The system then combines all of this into the sfPropelZSLSearch module and viola, you have a working search engine. The goal of this plugin is to be an instant search engine that can be easily added into other plugins, like sfSimpleCMSPlugin and sfSimpleBlogPlugin.
Plugin Status
This version is a rough "Proof of Concept" implementation. Use at your own risk! Right now, this documentation assumes that you are familar with symfony, Propel, and some basic knowledge of plugins.
Installation
Indexing
There are currently two supported ways to add documents to the search engine:
- Directly through the models, or
- Output from actions
The entire search engine is configured by search.yml files, located in your project's config directory, your applications' config directories, and your modules' config directories, which is where you set up the various indexing options.
Indexing Models
Setting up the plugin to index your models is easy. First, you must define the models you want to index in your project's search.yml file. The example below shows a search.yml for a blog:
models:
BlogPost:
fields:
title: keyword
content: unstored
author: unindexed
title: friendlytitle
BlogComment:
fields:
title: keyword
content: unstored
title: title
index:
name: MyIndex
encoding: UTF-8
See the Zend_Search_Lucene documentation for more about the field types.
If you look carefully at the above example, you will notice that the "title" for "!BlogPost" is set to the "friendlytitle" field. This means that when this model is returned, the title for the hit will be the friendly title. If you do not specify a title field, the system will guess the title.
Next, you need to tell the engine where to send the user should the model be returned. You do this by creating your application's config/search.yml and defining a route for the model:
models:
BlogPost:
route: blog/showPost?slug={$slug}
BlogComment:
route: blog/showComment?id={$id}
In routes, {$xxxx} is a token and will be replaced by the appropriate field value. So, {$slug} will be the value returned by ->getSlug() on the model.
Finally, you must register the models with the plugin so that they will automatically update the index. You can do this by opening up the model's file and putting
sfPZSLBehavior::getInitializer()->setupModel('MyModel');
after the class declaration. So, for a blog, you would open project/lib/model/BlogPost.php and append the above, replacing "!MyModel" with "!BlogPost". (Note: this is the same thing as a Propel behavior.)
You're now set. If you want to index your already existing data, simply run
$ symfony pzsl-rebuild application
on the command line, replacing "application" with your application.
Indexing Actions
Note: This is not recommended for dynamic data because the actions are only updated when you rebuild the index. Also, currently, it is not possible to index more than one application (if anyone has a nice way of doing this, let me know).
To setup an action to be indexed, you must create a file in the module's config directory named search.yml. Inside this file, you define the actions you want indexed:
privacy:
tos:
security:
authenticated: true
credentials: [admin]
disclaimer:
params:
advanced: true
layout: true
As you can see, it is possible to define request parameters, manipulate authentication, and toggle decorating the response. By default, the response is not decorated, the user is not authenticated without any credentials, and there aren't any request parameters.
After you have saved this file, you can rebuild the index by:
$ symfony pzsl-rebuild application
replacing "application" with the application name.
Searching the Index
The system ships with a very basic search interface that you can use as a search engine on your public application. To enable the engine, open the application's settings.yml file and in the enabled_modules section, add 'sfPropelZSLSearch'. It will look like:
all:
.settings:
enabled_modules: [sfPropelZSLSearch](default,)
You can now access the search engine in your project: http://localhost/myproject/web/sfPropelZSLSearch. You can define your own routes in the routing.yml file.
If you want to add a search box to your navigation for instance, simply make a call to the following component:
Customizing the Interface
You can customize the search results by overriding various templates and actions to tailor the look and feel to your application. To do this, first create the folder yourapp/modules/sfPropelZSLSearch. To override the templates, then create a templates directory: yourapp/modules/sfPropelZSLSearch/templates. To see the templates that you can override, browse to the files in plugins/sfPropelZSLSearchPlugin/modules/sfPropelZSLSearch/templates.
Often, when writing a search engine, you need to display a different result template for each model. For instance, a blog post should show differently than a forum post. You can easily customize your results by changing the "partial" value in your application's search.yml file. For example:
models:
BlogPost:
route: blog/showPost?slug={$slug}
partial: blog/searchResult
ForumPost:
route: forum/showThread?id={$id}
partial: forum/searchResult
The partial that you specify is given a $result object that you can use to build that result. The API for this object is pretty simple:
$result->getInternalTitle() returns the title of the search result.$result->getInternalRoute() returns the route to the search result.$result->getScore() returns the score / ranking of the search result.$result->getXXX() returns the XXX field.
Common Pitfals
- The webserver daemon and you need read and write access to the index. The index is stored in your project's data/index folder, so make sure that you can write to all the files and folders in that directory.
- You have to remember to define a route for each model, otherwise an exception will be thrown asking you to define a route.
- No, you cannot make POST requests during action indexing. POST requests indicate that the server state is being modified and the indexing agent should not be modifying anything.
To Do
- Indexes across applications
- I18n and L10n support
- Search highlighting based on referer
- More Lucene configuration (stop words, etc)
- Search help page
- Advanced search
- Unit tests
- Find a better way to paginate
- Improve the search interface (ajax?)
Contribute
Contributions and criticism are always welcome! :-)
Carl Vondrick 
-
Make a donation -
"symfony" is a trademark of Fabien Potencier. All rights reserved.
