File Coverage

blib/lib/Facebook/Graph/Query.pm
Criterion Covered Total %
statement 12 80 15.0
branch 0 28 0.0
condition n/a
subroutine 4 16 25.0
pod 13 13 100.0
total 29 137 21.1


line stmt bran cond sub pod time code
1             package Facebook::Graph::Query;
2             $Facebook::Graph::Query::VERSION = '1.1204';
3 4     4   25 use Moo;
  4         8  
  4         17  
4 4     4   1043 use Facebook::Graph::Request;
  4         9  
  4         98  
5             with 'Facebook::Graph::Role::Uri';
6 4     4   20 use URI::Escape;
  4         9  
  4         2898  
7              
8             has secret => (
9             is => 'ro',
10             required => 0,
11             predicate => 'has_secret',
12             );
13              
14             has access_token => (
15             is => 'ro',
16             predicate => 'has_access_token',
17             );
18              
19             has ids => (
20             is => 'rw',
21             predicate => 'has_ids',
22             lazy => 1,
23             default => sub { [] },
24             );
25              
26             has fields => (
27             is => 'rw',
28             predicate => 'has_fields',
29             lazy => 1,
30             default => sub { [] },
31             );
32              
33             has metadata => (
34             is => 'rw',
35             predicate => 'has_metadata',
36             );
37              
38             has limit => (
39             is => 'rw',
40             predicate => 'has_limit',
41             );
42              
43             has offset => (
44             is => 'rw',
45             predicate => 'has_offset',
46             );
47              
48             has datef => (
49             is => 'rw',
50             predicate => 'has_datef',
51             );
52              
53              
54             has search_query => (
55             is => 'rw',
56             predicate => 'has_search_query',
57             );
58              
59             has search_type => (
60             is => 'rw',
61             predicate => 'has_search_type',
62             );
63              
64             has object_name => (
65             is => 'rw',
66             default => sub {''},
67             );
68              
69             has until => (
70             is => 'rw',
71             predicate => 'has_until',
72             );
73              
74             has since => (
75             is => 'rw',
76             predicate => 'has_since',
77             );
78              
79             sub limit_results {
80 0     0 1 0 my ($self, $limit) = @_;
81 0         0 $self->limit($limit);
82 0         0 return $self;
83             }
84              
85             sub date_format {
86 0     0 1 0 my ($self, $date_format) = @_;
87 0         0 $self->datef($date_format);
88 0         0 return $self;
89             }
90              
91             sub find {
92 1     1 1 9 my ($self, $object_name) = @_;
93 1         5 $self->object_name($object_name);
94 1         3 return $self;
95             }
96              
97             sub search {
98 0     0 1   my ($self, $query, $type) = @_;
99 0           $self->search_query($query);
100 0 0         return ($type) ? $self->from($type) : $self;
101             }
102              
103             sub from {
104 0     0 1   my ($self, $type) = @_;
105 0 0         if ($type eq 'my_news') {
106 0           $self->object_name('me/home');
107             }
108             else {
109 0           $self->object_name('search');
110 0           $self->search_type($type);
111             }
112 0           return $self;
113             }
114              
115             sub offset_results {
116 0     0 1   my ($self, $offset) = @_;
117 0           $self->offset($offset);
118 0           return $self;
119             }
120              
121             sub include_metadata {
122 0     0 1   my ($self, $include) = @_;
123 0 0         $include = 1 unless defined $include;
124 0           $self->metadata($include);
125 0           return $self;
126             }
127              
128             sub select_fields {
129 0     0 1   my ($self, @fields) = @_;
130 0           push @{$self->fields}, @fields;
  0            
131 0           return $self;
132             }
133              
134             sub where_ids {
135 0     0 1   my ($self, @ids) = @_;
136 0           push @{$self->ids}, @ids;
  0            
137 0           return $self;
138             }
139              
140             sub where_until {
141 0     0 1   my ($self, $date) = @_;
142 0           $self->until($date);
143 0           return $self;
144             }
145              
146             sub where_since {
147 0     0 1   my ($self, $date) = @_;
148 0           $self->since($date);
149 0           return $self;
150             }
151              
152             sub uri_as_string {
153 0     0 1   my ($self) = @_;
154 0           my %query;
155 0 0         if ($self->has_access_token) {
156 0           $query{access_token} = uri_unescape($self->access_token);
157             }
158 0 0         if ($self->has_limit) {
159 0           $query{limit} = $self->limit;
160 0 0         if ($self->has_offset) {
161 0           $query{offset} = $self->offset;
162             }
163             }
164 0 0         if ($self->has_datef) {
165 0           $query{date_format} = $self->datef;
166             }
167 0 0         if ($self->has_search_query) {
168 0           $query{q} = $self->search_query;
169 0 0         if ($self->has_search_type) {
170 0           $query{type} = $self->search_type;
171             }
172             }
173 0 0         if ($self->has_until) {
174 0           $query{until} = $self->until;
175             }
176 0 0         if ($self->has_since) {
177 0           $query{since} = $self->since;
178             }
179 0 0         if ($self->has_metadata) {
180 0           $query{metadata} = $self->metadata;
181             }
182 0 0         if ($self->has_fields) {
183 0           $query{fields} = join(',', @{$self->fields});
  0            
184             }
185 0 0         if ($self->has_ids) {
186 0           $query{ids} = join(',', @{$self->ids});
  0            
187             }
188 0           my $uri = $self->uri;
189 0           $uri->path($self->generate_versioned_path($self->object_name));
190 0           $uri->query_form(%query);
191 0           return $uri->as_string;
192             }
193              
194             sub request {
195 0     0 1   my ($self) = @_;
196 0           return Facebook::Graph::Request->new->get($self->uri_as_string);
197             }
198              
199             1;
200              
201             =head1 NAME
202              
203             Facebook::Graph::Query - Simple and fast searching and fetching of Facebook data.
204              
205             =head1 VERSION
206              
207             version 1.1204
208              
209             =head1 SYNOPSIS
210              
211             my $fb = Facebook::Graph->new;
212            
213             my $perl_page = $fb->query->find('16665510298')
214             ->include_metadata
215             ->request
216             ->as_hashref;
217            
218             my $sarah_bownds = $fb->query->find('sarahbownds')
219             ->select_fields(qw(id name))
220             ->request
221             ->as_hashref;
222              
223             # this one would require an access token
224             my $new_years_posts = $fb->query
225             ->from('posts')
226             ->where_since('1 January 2011')
227             ->where_until('2 January 2011')
228             ->limit(25)
229             ->date_format('U')
230             ->request
231             ->as_hashref;
232              
233             # this one would require an access token
234             my $new_car_posts = $fb->query
235             ->search('car', 'my_news')
236             ->where_since('yesterday')
237             ->request
238             ->as_hashref;
239              
240              
241             =head1 DESCRIPTION
242              
243             This 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:
244              
245             my $results = $fb
246             ->select_fields(qw(id name))
247             ->search('Dave','user')
248             ->where_since('yesterday')
249             ->limit_results(25)
250             ->request
251             ->as_hashref;
252            
253             The 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."
254              
255              
256             =head1 METHODS
257              
258             =head2 find ( id )
259              
260             Fetch a single item.
261              
262             =head3 id
263              
264             The unique id or object name of an object.
265              
266             B<Example:> For user "Sarah Bownds" you could use either her profile id C<sarahbownds> or her object id C<767598108>.
267              
268              
269              
270              
271             =head2 from ( context )
272              
273              
274              
275             If you prefer to search by keyword see the C<search> method.
276              
277             =head3 context
278              
279             One of the following contexts:
280              
281             =over
282              
283             =item my_news
284              
285             The current user's news feed (home page). Requires that you have an access_token so you know who the current user is.
286              
287             =item post
288              
289             All public posts.
290              
291             =item user
292              
293             All people.
294              
295             =item page
296              
297             All pages.
298              
299             =item event
300              
301             All events.
302              
303             =item group
304              
305             All groups.
306              
307             =back
308              
309              
310              
311             =head2 search ( query, context )
312              
313             Perform a keyword search on a group of items.
314              
315             If you prefer not to search by keyword see the C<from> method.
316              
317             =head3 query
318              
319             They keywords to search by.
320              
321             =head3 context
322              
323             See the C<context> param in the C<from> method.
324              
325              
326              
327             =head2 limit_results ( amount )
328              
329             The 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.
330              
331             =head2 date_format ( format )
332              
333             The result set dates will be formatted in the defined formats. Specify the format by reference the PHP date format spec: L<http://php.net/manual/en/function.date.php>. (eg. ->date_format('U')->) Useful for getting epoch for datatime. Returns C<$self> for method chaining.
334              
335             =head3 amount
336              
337             An integer representing the number of records to be returned.
338              
339              
340              
341             =head2 offset_results ( amount )
342              
343             Skips 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              
347             An integer representing the amount to offset the results by.
348              
349              
350              
351             =head2 include_metadata ( [ include ] )
352              
353             Adds 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              
357             Defaults 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              
362             Limit 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              
366             An array of fields you want in the result set.
367              
368             B<Example:> 'id', 'name', 'picture'
369              
370              
371             =head2 where_ids ( ids )
372              
373             Limit 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              
377             An array of object ids, object names, or URIs.
378              
379             B<Example:> 'http://www.thegamecrafter.com/', 'sarahbownds', '16665510298'
380              
381              
382             =head2 where_until ( date )
383              
384             Include only records that were created before C<date>. Returns C<$self> for method chaining.
385              
386             =head3 date
387              
388             Anything accepted by PHP's strtotime function L<http://php.net/manual/en/function.strtotime.php>.
389              
390              
391             =head2 where_since ( date )
392              
393             Include only records that have been created since C<date>. Returns C<$self> for method chaining.
394              
395             =head3 date
396              
397             Anything accepted by PHP's strtotime function L<http://php.net/manual/en/function.strtotime.php>.
398              
399              
400             =head2 uri_as_string ()
401              
402             Returns 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              
408             Forms 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              
412             Optionally 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              
417             Facebook::Graph is Copyright 2010 - 2012 Plain Black Corporation (L<http://www.plainblack.com>) and is licensed under the same terms as Perl itself.
418              
419             =cut