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

release-1.10release-1.9
Last change on this file since e4b8f93 was b7fa912, checked in by Edward Z. Yang <ezyang@mit.edu>, 13 years ago
Force void context on callbacks. Signed-off-by: Edward Z. Yang <ezyang@mit.edu>
  • Property mode set to 100644
File size: 8.8 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 AnyEvent::HTTP;
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, $cb) = @_;
186    my $uri = $self->uri_as_string;
187    http_get $uri, sub {
188        my ($response, $headers) = @_;
189        my %params = (
190            response => $response,
191            headers => $headers,
192            uri => $uri
193        );
194        if ($self->has_secret) {
195            $params{secret} = $self->secret;
196        }
197        $cb->(Facebook::Graph::Response->new(%params));
198    };
199    () # return nothing
200}
201
202no Any::Moose;
203__PACKAGE__->meta->make_immutable;
204
205
206=head1 NAME
207
208Facebook::Graph::Query - Simple and fast searching and fetching of Facebook data.
209
210=head1 VERSION
211
212version 1.0300
213
214=head1 SYNOPSIS
215
216 my $fb = Facebook::Graph->new;
217 
218 my $perl_page = $fb->find('16665510298')
219    ->include_metadata
220    ->request
221    ->as_hashref;
222 
223 my $sarah_bownds = $fb->find('sarahbownds')
224    ->select_fields(qw(id name))
225    ->request
226    ->as_hashref;
227
228 # this one would require an access token
229 my $new_years_posts = $fb->query
230    ->from('posts')
231    ->where_since('1 January 2011')
232    ->where_until('2 January 2011')
233    ->limit(25)
234    ->request
235    ->as_hashref;
236
237 # this one would require an access token
238 my $new_car_posts = $fb->query
239    ->search('car', 'my_news')
240    ->where_since('yesterday')
241    ->request
242    ->as_hashref;
243
244
245=head1 DESCRIPTION
246
247This 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:
248
249 my $results = $fb
250    ->select_fields(qw(id name))
251    ->search('Dave','user')
252    ->where_since('yesterday')
253    ->limit_results(25)
254    ->request
255    ->as_hashref;
256   
257The 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."
258
259
260=head1 METHODS
261
262=head2 find ( id )
263
264Fetch a single item.
265
266=head3 id
267
268The unique id or object name of an object.
269
270B<Example:> For user "Sarah Bownds" you could use either her profile id C<sarahbownds> or her object id C<767598108>.
271
272
273
274
275=head2 from ( context )
276
277
278
279If you prefer to search by keyword see the C<search> method.
280
281=head3 context
282
283One of the following contexts:
284
285=over
286
287=item my_news
288
289The current user's news feed (home page). Requires that you have an access_token so you know who the current user is.
290
291=item post
292
293All public posts.
294
295=item user
296
297All people.
298
299=item page
300
301All pages.
302
303=item event
304
305All events.
306
307=item group
308
309All groups.
310
311
312
313
314=head2 search ( query, context )
315
316Perform a keyword search on a group of items.
317
318If you prefer not to search by keyword see the C<from> method.
319
320=head3 query
321
322They keywords to search by.
323
324=head3 context
325
326See the C<context> param in the C<from> method.
327
328=back
329
330
331
332=head2 limit_results ( amount )
333
334The 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.
335
336=head3 amount
337
338An integer representing the number of records to be returned.
339
340
341
342=head2 offset_results ( amount )
343
344Skips 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.
345
346=head3 amount
347
348An integer representing the amount to offset the results by.
349
350
351
352=head2 include_metadata ( [ include ] )
353
354Adds metadata to the result set including things like connections to other objects and the object type being returned. Returns C<$self> for method chaining.
355
356=head3 include
357
358Defaults 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.
359
360
361=head2 select_fields ( fields )
362
363Limit 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.
364
365=head3 fields
366
367An array of fields you want in the result set.
368
369B<Example:> 'id', 'name', 'picture'
370
371
372=head2 where_ids ( ids )
373
374Limit the result set to these specifically identified objects. Returns C<$self> for method chaining. May be called multiple times to add more ids.
375
376=head3 ids
377
378An array of object ids, object names, or URIs.
379
380B<Example:> 'http://www.thegamecrafter.com/', 'sarahbownds', '16665510298'
381
382
383=head2 where_until ( date )
384
385Include only records that were created before C<date>. Returns C<$self> for method chaining.
386
387=head3 date
388
389Anything accepted by PHP's strtotime function L<http://php.net/manual/en/function.strtotime.php>.
390
391
392=head2 where_since ( date )
393
394Include only records that have been created since C<date>. Returns C<$self> for method chaining.
395
396=head3 date
397
398Anything accepted by PHP's strtotime function L<http://php.net/manual/en/function.strtotime.php>.
399
400
401=head2 uri_as_string ()
402
403Returns 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.
404
405
406
407=head2 request ( [ uri ] )
408
409Forms a URI string based on every method you've called so far, and fetches the data. Returns a L<Facebook::Graph::Response> object.
410
411=head3 uri
412
413Optionally 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.
414
415
416=head1 LEGAL
417
418Facebook::Graph is Copyright 2010 Plain Black Corporation (L<http://www.plainblack.com>) and is licensed under the same terms as Perl itself.
419
420=cut
Note: See TracBrowser for help on using the repository browser.