source: perl/modules/Facebook/lib/Facebook/Graph/Query.pm @ cfca761

Last change on this file since cfca761 was cfca761, checked in by Edward Z. Yang <ezyang@mit.edu>, 13 years ago
Add vanilla Facebook::Graph. Signed-off-by: Edward Z. Yang <ezyang@mit.edu>
  • Property mode set to 100644
File size: 8.7 KB
Line 
1package Facebook::Graph::Query;
2BEGIN {
3  $Facebook::Graph::Query::VERSION = '1.0300';
4}
5
6use Any::Moose;
7use Facebook::Graph::Response;
8with 'Facebook::Graph::Role::Uri';
9use LWP::UserAgent;
10use URI::Encode qw(uri_decode);
11
12has secret => (
13    is          => 'ro',
14    required    => 0,
15    predicate   => 'has_secret',
16);
17
18has access_token => (
19    is          => 'ro',
20    predicate   => 'has_access_token',
21);
22
23has ids => (
24    is          => 'rw',
25    predicate   => 'has_ids',
26    lazy        => 1,
27    default     => sub { [] },
28);
29
30has fields => (
31    is          => 'rw',
32    predicate   => 'has_fields',
33    lazy        => 1,
34    default     => sub { [] },
35);
36
37has metadata => (
38    is          => 'rw',
39    predicate   => 'has_metadata',
40);
41
42has limit => (
43    is          => 'rw',
44    predicate   => 'has_limit',
45);
46
47has offset => (
48    is          => 'rw',
49    predicate   => 'has_offset',
50);
51
52has search_query => (
53    is          => 'rw',
54    predicate   => 'has_search_query',
55);
56
57has search_type => (
58    is          => 'rw',
59    predicate   => 'has_search_type',
60);
61
62has object_name => (
63    is          => 'rw',
64    default     => '',
65);
66
67has until => (
68    is          => 'rw',
69    predicate   => 'has_until',
70);
71
72has since => (
73    is          => 'rw',
74    predicate   => 'has_since',
75);
76
77
78sub limit_results {
79    my ($self, $limit) = @_;
80    $self->limit($limit);
81    return $self;   
82}
83
84sub find {
85    my ($self, $object_name) = @_;
86    $self->object_name($object_name);
87    return $self;
88}
89
90sub search {
91    my ($self, $query, $type) = @_;
92    $self->search_query($query);
93    return ($type) ? $self->from($type) : $self;
94}
95
96sub from {
97    my ($self, $type) = @_;
98    if ($type eq 'my_news') {
99        $self->object_name('me/home');
100    }
101    else {
102        $self->object_name('search');
103        $self->search_type($type);
104    }
105    return $self;
106}
107
108sub offset_results {
109    my ($self, $offset) = @_;
110    $self->offset($offset);
111    return $self;   
112}
113
114sub include_metadata {
115    my ($self, $include) = @_;
116    $include = 1 unless defined $include;
117    $self->metadata($include);
118    return $self;
119}
120
121sub select_fields {
122    my ($self, @fields) = @_;
123    push @{$self->fields}, @fields;
124    return $self;
125}
126
127sub where_ids {
128    my ($self, @ids) = @_;
129    push @{$self->ids}, @ids;
130    return $self;
131}
132
133sub where_until {
134    my ($self, $date) = @_;
135    $self->until($date);
136    return $self;
137}
138
139sub where_since {
140    my ($self, $date) = @_;
141    $self->since($date);
142    return $self;
143}
144
145sub uri_as_string {
146    my ($self) = @_;
147    my %query;
148    if ($self->has_access_token) {
149        $query{access_token} = uri_decode($self->access_token);
150    }
151    if ($self->has_limit) {
152        $query{limit} = $self->limit;
153        if ($self->has_offset) {
154            $query{offset} = $self->offset;
155        }
156    }
157    if ($self->has_search_query) {
158        $query{q} = $self->search_query;
159        if ($self->has_search_type) {
160            $query{type} = $self->search_type;
161        }
162    }
163    if ($self->has_until) {
164        $query{until} = $self->until;
165    }
166    if ($self->has_since) {
167        $query{since} = $self->since;
168    }
169    if ($self->has_metadata) {
170        $query{metadata} = $self->metadata;
171    }
172    if ($self->has_fields) {
173        $query{fields} = join(',', @{$self->fields});
174    }
175    if ($self->has_ids) {
176        $query{ids} = join(',', @{$self->ids});
177    }
178    my $uri = $self->uri;
179    $uri->path($self->object_name);
180    $uri->query_form(%query);
181    return $uri->as_string;
182}
183
184sub request {
185    my ($self, $uri) = @_;
186    $uri ||= $self->uri_as_string;
187    my $response = LWP::UserAgent->new->get($uri);
188    my %params = (response => $response);
189    if ($self->has_secret) {
190        $params{secret} = $self->secret;
191    }
192    return Facebook::Graph::Response->new(%params);
193}
194
195no Any::Moose;
196__PACKAGE__->meta->make_immutable;
197
198
199=head1 NAME
200
201Facebook::Graph::Query - Simple and fast searching and fetching of Facebook data.
202
203=head1 VERSION
204
205version 1.0300
206
207=head1 SYNOPSIS
208
209 my $fb = Facebook::Graph->new;
210 
211 my $perl_page = $fb->find('16665510298')
212    ->include_metadata
213    ->request
214    ->as_hashref;
215 
216 my $sarah_bownds = $fb->find('sarahbownds')
217    ->select_fields(qw(id name))
218    ->request
219    ->as_hashref;
220
221 # this one would require an access token
222 my $new_years_posts = $fb->query
223    ->from('posts')
224    ->where_since('1 January 2011')
225    ->where_until('2 January 2011')
226    ->limit(25)
227    ->request
228    ->as_hashref;
229
230 # this one would require an access token
231 my $new_car_posts = $fb->query
232    ->search('car', 'my_news')
233    ->where_since('yesterday')
234    ->request
235    ->as_hashref;
236
237
238=head1 DESCRIPTION
239
240This module presents a programatic approach to building the queries necessary to search and retrieve Facebook data. It provides an almost SQL like way of writing queries using code. For example:
241
242 my $results = $fb
243    ->select_fields(qw(id name))
244    ->search('Dave','user')
245    ->where_since('yesterday')
246    ->limit_results(25)
247    ->request
248    ->as_hashref;
249   
250The above query, if you were read it like text, says: "Give me the user ids and full names of all users named Dave that have been created since yesterday, and limit the result set to the first 25."
251
252
253=head1 METHODS
254
255=head2 find ( id )
256
257Fetch a single item.
258
259=head3 id
260
261The unique id or object name of an object.
262
263B<Example:> For user "Sarah Bownds" you could use either her profile id C<sarahbownds> or her object id C<767598108>.
264
265
266
267
268=head2 from ( context )
269
270
271
272If you prefer to search by keyword see the C<search> method.
273
274=head3 context
275
276One of the following contexts:
277
278=over
279
280=item my_news
281
282The current user's news feed (home page). Requires that you have an access_token so you know who the current user is.
283
284=item post
285
286All public posts.
287
288=item user
289
290All people.
291
292=item page
293
294All pages.
295
296=item event
297
298All events.
299
300=item group
301
302All groups.
303
304
305
306
307=head2 search ( query, context )
308
309Perform a keyword search on a group of items.
310
311If you prefer not to search by keyword see the C<from> method.
312
313=head3 query
314
315They keywords to search by.
316
317=head3 context
318
319See the C<context> param in the C<from> method.
320
321=back
322
323
324
325=head2 limit_results ( amount )
326
327The result set will only return a certain number of records when this is set. Useful for paging result sets. Returns C<$self> for method chaining.
328
329=head3 amount
330
331An integer representing the number of records to be returned.
332
333
334
335=head2 offset_results ( amount )
336
337Skips ahead the result set by the amount. Useful for paging result sets. Is only applied when used in combination with C<limit_results>. Returns C<$self> for method chaining.
338
339=head3 amount
340
341An integer representing the amount to offset the results by.
342
343
344
345=head2 include_metadata ( [ include ] )
346
347Adds metadata to the result set including things like connections to other objects and the object type being returned. Returns C<$self> for method chaining.
348
349=head3 include
350
351Defaults to 1 when the method is called, but defaults to 0 if the method is never called. You may set it specifically by passing in a 1 or 0.
352
353
354=head2 select_fields ( fields )
355
356Limit the result set to only include the specific fields if they exist in the objects in the result set. Returns C<$self> for method chaining. May be called multiple times to add more fields.
357
358=head3 fields
359
360An array of fields you want in the result set.
361
362B<Example:> 'id', 'name', 'picture'
363
364
365=head2 where_ids ( ids )
366
367Limit the result set to these specifically identified objects. Returns C<$self> for method chaining. May be called multiple times to add more ids.
368
369=head3 ids
370
371An array of object ids, object names, or URIs.
372
373B<Example:> 'http://www.thegamecrafter.com/', 'sarahbownds', '16665510298'
374
375
376=head2 where_until ( date )
377
378Include only records that were created before C<date>. Returns C<$self> for method chaining.
379
380=head3 date
381
382Anything accepted by PHP's strtotime function L<http://php.net/manual/en/function.strtotime.php>.
383
384
385=head2 where_since ( date )
386
387Include only records that have been created since C<date>. Returns C<$self> for method chaining.
388
389=head3 date
390
391Anything accepted by PHP's strtotime function L<http://php.net/manual/en/function.strtotime.php>.
392
393
394=head2 uri_as_string ()
395
396Returns a URI string based upon all the methods you've called so far on the query. Mainly useful for debugging. Usually you want to call C<request> and have it fetch the data for you.
397
398
399
400=head2 request ( [ uri ] )
401
402Forms a URI string based on every method you've called so far, and fetches the data. Returns a L<Facebook::Graph::Response> object.
403
404=head3 uri
405
406Optionally pass in your own URI string and all the other options will be ignored. This is mainly useful with metadata connections. See C<include_metadata> for details.
407
408
409=head1 LEGAL
410
411Facebook::Graph is Copyright 2010 Plain Black Corporation (L<http://www.plainblack.com>) and is licensed under the same terms as Perl itself.
412
413=cut
Note: See TracBrowser for help on using the repository browser.