-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
199 lines (107 loc) · 6.91 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
# sfPropelSlopeOneRecommendationsPlugin
sfPropelSlopeOneRecommendationsPlugin is a symfony plugin that enables collaborative filtering based on the [Slope One algorithms](http://en.wikipedia.org/wiki/Slope_One). The plugin supports two scenarios:
* Recommending new items to a user based on his/her previous ratings
* Recommending other items with similar ratings as a specific item
sfPropelSlopeOneRecommendationsPlugin consists of Propel behaviors for retrieving recommendations and tasks for maintaining the underlying datastructure for the recommendations.
This plugin supports but does not require [sfGuardPlugin](http://www.symfony-project.org/plugins/sfGuardPlugin) for user management and [sfPropelActAsRatableBehaviorPlugin](http://www.symfony-project.org/plugins/sfPropelActAsRatableBehaviorPlugin) for ratings through flexible configuration options.
## Installation
* Install the plugin
> php symfony plugin-install http://plugins.symfony-project.com/sfPropelSlopeOneRecommendationsPlugin
* If not already done, enabled behaviors in ``config/propel.ini``:
> propel.builder.addBehaviors = true
* Rebuild the model
> php symfony propel-build-model
> php symfony propel-build-sql
* Update your database tables by starting from scratch (it will delete all the existing tables, then re-create them):
> php symfony propel-insert-sql
or you can create the new table by using the generated SQL statements in ``data/sql/plugins.sfPropelSlopeOneRecommendationsPlugin.lib.model.schema.sql``.
* Clear the cache
> php symfony cc
## Configuration
If you use the default configuration of [sfPropelActAsRatableBehaviorPlugin](http://www.symfony-project.org/plugins/sfPropelActAsRatableBehaviorPlugin) then sfPropelSlopeOneRecommendationsPlugin does not require further configuration.
If you use another method for handling user ratings then copy the content from the sample ``app.yml`` provided with the plugin to your application ``app.yml``:
* The table which holds user item ratings
rating_table: sf_ratings
* The column which holds ids of users
rater_id_column: user_id
* The column which holds the class name of rated objects
rateable_model_column: ratable_model
* The column which holds the id of rated objects
rateable_id_column: ratable_id
* The column which holds value of item ratings
rating_column: rating
## Usage
### Recommendations
sfPropelSlopeOneRecommendationsPlugin supports two types of recommendations:
* Recommendations of new items to a user based on his/her previous ratings
* Recommendations of other items with similar ratings as a specific item
#### User recommendations
To retrieve recommendations of new items to a user based on his/her previous ratings the user class must have the ``sfPropelActAsSlopeOneRaterBehavior``.
This can be added in two ways:
* In ``schema.yml`` (since symfony 1.1)
propel:
user:
id:
[...]
_behaviors:
sfPropelActAsSlopeOneRaterBehavior: { }
* Programmatically
[php]
sfPropelBehavior::add('sfGuardUser', array('sfPropelActAsSlopeOneRaterBehavior'));
Note that if you do not use [sfGuardPlugin](http://www.symfony-project.org/plugins/sfGuardPlugin) for user management your user class must implement a ``getId()`` method which returns a unique id.
When the behavior has been added you can now call ``getRecommendations($itemClass, $numRecommendations)``:
[php]
//get 10 recommended Item objects for the user
$recommendations = $user->getRecommentations('Item', 10);
The recommendations are always ordered with the best recommendation first. Recommendations never contain objects which the user has already rated so if the user has rated all objects then ``getRecommendations()`` will return an empty array.
#### Item recommendations
To retrieve recommendations of other items with similar ratings to a specific item the item class must have the ``sfPropelActAsSlopeOneRateableBehavior``.
This can be added in two ways:
* In ``schema.yml`` (since symfony 1.1)
propel:
item:
id:
[...]
_behaviors:
sfPropelActAsSlopeOneRateableBehavior: { }
* Programmatically
[php]
sfPropelBehavior::add('Item', array('sfPropelActAsSlopeOneRateableBehavior'));
Note that your item class must implement a ``getId()`` method which returns a unique id.
When the behavior has been added you can now call ``getRecommendations($numRecommendations)``:
[php]
//get 10 recommended Item objects based on the rating of the current item
$recommendations = $item->getRecommentations(10);
The recommendations are always ordered with the best recommendation first.
#### Recommendation objects
The objects returned by the two ``getRecommendations()`` will actually be of type ``sfPropelSlopeOneRecommendation``. This class implements two methods:
* ``getRecommendationRating()`` which returns the expected rating of the returned object
* ``getRecommendationObject()`` which returns the actual recommended object
In all other concerns ``sfPropelSlopeOneRecommendation`` acts as a transparent wrapper class for the recommended object by passing calls to all other methods to this object.
An array of ``sfPropelSlopeOneRecommendation`` objects returned by ``getRecommendations()`` will be sorted by descending value returned by ``getRecommendationRating()``.
### Maintenance
The Slope One implementation used in this plugin uses a database table containing precalculated rating relations between items. Data in this table needs to be updated on a regular basis to for recommendations to reflect the latest ratings.
#### Task-based maintenance
To maintain this you can invoke either of the provided tasks:
* The MySQL task creates a ``slope_one`` stored procedure for maintaining the table and executes this. This will usually be faster than running the PHP task. This is recommended for production use if you use MySQL 5.1 verson which supports stored procedures.
> php symfony slopeone:build-mysql
* The PHP task uses a combination of PHP and standard SQL queries for maintaining the data.
> php symfony slopeone:build-php
Depending on the number of items and ratings in your application maintenance can be time consuming and it suitable for a nightly cron job.
#### Programmatic maintenance
It is also possible to invoke the maintenance programmatically:
* The MySQL approach:
[php]
$builder = new sfPropelSlopeOneMySqlBuilder(new sfPropelSlopeOneSqlParser());
$builder->build();
* The PHP approach:
[php]
$builder = new sfPropelSlopeOnePhpBuilder(new sfPropelSlopeOneSqlParser());
$builder->build();
##Credits
The Slope One algorithmns were introduced in [*Slope One Predictors for Online Rating-Based Collaborative Filtering*](http://www.daniel-lemire.com/fr/abstracts/SDM2005.html) by Daniel Lemire and Anna Maclachlan.
sfPropelSlopeOneRecommendationsPlugin is heavily inspired by the [OpenSlopeOne project](http://code.google.com/p/openslopeone/) by Chaoqun Fu.
## TODO / Ideas
## Changelog
### 2009-05-05 | 0.1.0 Alpha
* Initial release