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

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