Simplify guarded pass-through added to CDBI in ee333775
[dbsrgits/DBIx-Class.git] / lib / DBIx / Class / MethodAttributes.pm
1 package DBIx::Class::MethodAttributes;
2
3 use strict;
4 use warnings;
5
6 use DBIx::Class::_Util qw( uniq refdesc visit_namespaces );
7 use Scalar::Util qw( weaken refaddr );
8
9 use namespace::clean;
10
11 my ( $attr_cref_registry, $attr_cache_active );
12 sub DBIx::Class::__Attr_iThreads_handler__::CLONE {
13
14   # This is disgusting, but the best we can do without even more surgery
15   # Note the if() at the end - we do not run this crap if we can help it
16   visit_namespaces( action => sub {
17     my $pkg = shift;
18
19     # skip dangerous namespaces
20     return 1 if $pkg =~ /^ (?:
21       DB | next | B | .+? ::::ISA (?: ::CACHE ) | Class::C3
22     ) $/x;
23
24     no strict 'refs';
25
26     if (
27       exists ${"${pkg}::"}{__cag___attr_cache}
28         and
29       ref( my $attr_stash = ${"${pkg}::__cag___attr_cache"} ) eq 'HASH'
30     ) {
31       $attr_stash->{ $attr_cref_registry->{$_}{weakref} } = delete $attr_stash->{$_}
32         for keys %$attr_stash;
33     }
34
35     return 1;
36   }) if $attr_cache_active;
37
38   # renumber the cref registry itself
39   %$attr_cref_registry = map {
40     ( defined $_->{weakref} )
41       ? (
42         # because of how __attr_cache works, ugh
43         "$_->{weakref}"         => $_,
44       )
45       : ()
46   } values %$attr_cref_registry;
47 }
48
49 sub MODIFY_CODE_ATTRIBUTES {
50   my $class = shift;
51   my $code = shift;
52
53   my $attrs;
54   $attrs->{
55     $_ =~ /^[a-z]+$/  ? 'builtin'
56   : $_ =~ /^DBIC_/    ? 'dbic'
57   :                     'misc'
58   }{$_}++ for @_;
59
60
61   # compaction step
62   defined $attr_cref_registry->{$_}{weakref} or delete $attr_cref_registry->{$_}
63     for keys %$attr_cref_registry;
64
65   # The original misc-attr API used stringification instead of refaddr - can't change that now
66   if( $attr_cref_registry->{$code} ) {
67     Carp::confess( sprintf
68       "Coderefs '%s' and '%s' stringify to the same value '%s': nothing will work",
69       refdesc($code),
70       refdesc($attr_cref_registry->{$code}{weakref}),
71       "$code"
72     ) if refaddr($attr_cref_registry->{$code}{weakref}) != refaddr($code);
73   }
74   else {
75     weaken( $attr_cref_registry->{$code}{weakref} = $code )
76   }
77
78
79   # increment the pkg gen, this ensures the sanity checkers will re-evaluate
80   # this class when/if the time comes
81   mro::method_changed_in($class) if (
82     ! DBIx::Class::_ENV_::OLD_MRO
83       and
84     ( $attrs->{dbic} or $attrs->{misc} )
85   );
86
87
88   # handle legacy attrs
89   if( $attrs->{misc} ) {
90
91     # if the user never tickles this - we won't have to do a gross
92     # symtable scan in the ithread handler above, so:
93     #
94     # User - please don't tickle this
95     $attr_cache_active = 1;
96
97     $class->mk_classaccessor('__attr_cache' => {})
98       unless $class->can('__attr_cache');
99
100     $class->__attr_cache->{$code} = [ sort( uniq(
101       @{ $class->__attr_cache->{$code} || [] },
102       keys %{ $attrs->{misc} },
103     ))];
104   }
105
106
107   # handle DBIC_* attrs
108   if( $attrs->{dbic} ) {
109     my $slot = $attr_cref_registry->{$code};
110
111     $slot->{attrs} = [ uniq
112       @{ $slot->{attrs} || [] },
113       grep {
114         $class->VALID_DBIC_CODE_ATTRIBUTE($_)
115           or
116         Carp::confess( "DBIC-specific attribute '$_' did not pass validation by $class->VALID_DBIC_CODE_ATTRIBUTE() as described in DBIx::Class::MethodAttributes" )
117       } keys %{$attrs->{dbic}},
118     ];
119   }
120
121
122   # FIXME - DBIC essentially gobbles up any attribute it can lay its hands on:
123   # decidedly not cool
124   #
125   # There should be some sort of warning on unrecognized attributes or
126   # somesuch... OTOH people do use things in the wild hence the plan of action
127   # is anything but clear :/
128   #
129   # https://metacpan.org/source/ZIGOROU/DBIx-Class-Service-0.02/lib/DBIx/Class/Service.pm#L93-110
130   # https://metacpan.org/source/ZIGOROU/DBIx-Class-Service-0.02/t/lib/DBIC/Test/Service/User.pm#L29
131   # https://metacpan.org/source/ZIGOROU/DBIx-Class-Service-0.02/t/lib/DBIC/Test/Service/User.pm#L36
132   #
133   # For the time being reuse the old logic for any attribute we do not have
134   # explicit plans for (i.e. stuff that is neither reserved, nor DBIC-internal)
135   #
136   # Pass the "builtin attrs" onwards, as the DBIC internals can't possibly  handle them
137   return sort keys %{ $attrs->{builtin} || {} };
138 }
139
140 # Address the above FIXME halfway - if something (e.g. DBIC::Helpers) wants to
141 # add extra attributes - it needs to override this in its base class to allow
142 # for 'return 1' on the newly defined attributes
143 sub VALID_DBIC_CODE_ATTRIBUTE {
144   #my ($class, $attr) = @_;
145
146 ###
147 ### !!! IMPORTANT !!!
148 ###
149 ### *DO NOT* yield to the temptation of using free-form-argument attributes.
150 ### The technique was proven instrumental in Catalyst a decade ago, and
151 ### was more recently revived in Sub::Attributes. Yet, while on the surface
152 ### they seem immensely useful, per-attribute argument lists are in fact an
153 ### architectural dead end.
154 ###
155 ### In other words: you are *very strongly urged* to ensure the regex below
156 ### does not allow anything beyond qr/^ DBIC_method_is_ [A-Z_a-z0-9]+ $/x
157 ###
158
159   $_[1] =~ /^ DBIC_method_is_ (?:
160     indirect_sugar
161       |
162     (?: bypassable | mandatory ) _resultsource_proxy
163       |
164     generated_from_resultsource_metadata
165       |
166     (?: inflated_ | filtered_ )? column_ (?: extra_)? accessor
167       |
168     single_relationship_accessor
169       |
170     (?: multi | filter ) _relationship_ (?: extra_ )? accessor
171       |
172     proxy_to_relationship
173       |
174     m2m_ (?: extra_)? sugar (?:_with_attrs)?
175   ) $/x;
176 }
177
178 sub FETCH_CODE_ATTRIBUTES {
179   #my ($class,$code) = @_;
180
181   sort(
182     @{ $_[0]->_attr_cache->{$_[1]} || [] },
183     ( defined( $attr_cref_registry->{$_[1]}{ weakref } )
184       ? @{ $attr_cref_registry->{$_[1]}{attrs} || [] }
185       : ()
186     ),
187   )
188 }
189
190 sub _attr_cache {
191   my $self = shift;
192   +{
193     %{ $self->can('__attr_cache') ? $self->__attr_cache : {} },
194     %{ $self->maybe::next::method || {} },
195   };
196 }
197
198 1;
199
200 __END__
201
202 =head1 NAME
203
204 DBIx::Class::MethodAttributes - DBIC-specific handling of CODE attributes
205
206 =head1 SYNOPSIS
207
208  my @attrlist = attributes::get( \&My::App::Schema::Result::some_method )
209
210 =head1 DESCRIPTION
211
212 This class provides the L<DBIx::Class> inheritance chain with the bits
213 necessary for L<attribute|attributes> support on methods.
214
215 Historically DBIC has accepted any string as a C<CODE> attribute and made
216 such strings available via the semi-private L</_attr_cache> method. This
217 was used for e.g. the long-deprecated L<DBIx::Class::ResultSetManager>,
218 but also has evidence of use on both C<CPAN> and C<DarkPAN>.
219
220 Starting mid-2016 DBIC treats any method attribute starting with C<DBIC_>
221 as an I<internal boolean decorator> for various DBIC-related methods.
222 Unlike the general attribute naming policy, strict whitelisting is imposed
223 on attribute names starting with C<DBIC_> as described in
224 L</VALID_DBIC_CODE_ATTRIBUTE> below.
225
226 =head2 DBIC-specific method attributes
227
228 The following method attributes are currently recognized under the C<DBIC_*>
229 prefix:
230
231 =head3 DBIC_method_is_indirect_sugar
232
233 The presence of this attribute indicates a helper "sugar" method. Overriding
234 such methods in your subclasses will be of limited success at best, as DBIC
235 itself and various plugins are much more likely to invoke alternative direct
236 call paths, bypassing your override entirely. Good examples of this are
237 L<DBIx::Class::ResultSet/create> and L<DBIx::Class::Schema/connect>.
238
239 See also the check
240 L<DBIx::Class::Schema::SanityChecker/no_indirect_method_overrides>.
241
242 =head3 DBIC_method_is_mandatory_resultsource_proxy
243
244 =head3 DBIC_method_is_bypassable_resultsource_proxy
245
246 The presence of one of these attributes on a L<proxied ResultSource
247 method|DBIx::Class::Manual::ResultClass/DBIx::Class::ResultSource> indicates
248 how DBIC will behave when someone calls e.g.:
249
250   $some_result->result_source->add_columns(...)
251
252 as opposed to the conventional
253
254   SomeResultClass->add_columns(...)
255
256 This distinction becomes important when someone declares a sub named after
257 one of the (currently 22) methods proxied from a
258 L<Result|DBIx::Class::Manual::ResultClass> to
259 L<ResultSource|DBIx::Class::ResultSource>. While there are obviously no
260 problems when these methods are called at compile time, there is a lot of
261 ambiguity whether an override of something like
262 L<columns_info|DBIx::Class::ResultSource/columns_info> will be respected by
263 DBIC and various plugins during runtime operations.
264
265 It must be noted that there is a reason for this weird situation: during the
266 original design of DBIC the "ResultSourceProxy" system was established in
267 order to allow easy transition from Class::DBI. Unfortunately it was not
268 well abstracted away: it is rather difficult to use a custom ResultSource
269 subclass. The expansion of the DBIC project never addressed this properly
270 in the years since. As a result when one wishes to override a part of the
271 ResultSource functionality, the overwhelming practice is to hook a method
272 in a Result class and "hope for the best".
273
274 The subtle changes of various internal call-chains in C<DBIC v0.0829xx> make
275 this silent uncertainty untenable. As a solution any such override will now
276 issue a descriptive warning that it has been bypassed during a
277 C<< $rsrc->overridden_function >> invocation. A user B<must> determine how
278 each individual override must behave in this situation, and tag it with one
279 of the above two attributes.
280
281 Naturally any override marked with C<..._bypassable_resultsource_proxy> will
282 behave like it did before: it will be silently ignored. This is the attribute
283 you want to set if your code appears to work fine, and you do not wish to
284 receive the warning anymore (though you are strongly encouraged to understand
285 the other option).
286
287 However overrides marked with C<..._mandatory_resultsource_proxy> will always
288 be reinvoked by DBIC itself, so that any call of the form:
289
290   $some_result->result_source->columns_info(...)
291
292 will be transformed into:
293
294   $some_result->result_source->result_class->columns_info(...)
295
296 with the rest of the callchain flowing out of that (provided the override did
297 invoke L<next::method|mro/next::method> where appropriate)
298
299 =head3 DBIC_method_is_generated_from_resultsource_metadata
300
301 This attribute is applied to all methods dynamically installed after various
302 invocations of L<ResultSource metadata manipulation
303 methods|DBIx::Class::Manual::ResultClass/DBIx::Class::ResultSource>. Notably
304 this includes L<add_columns|DBIx::Class::ResultSource/add_columns>,
305 L<add_relationship|DBIx::Class::ResultSource/add_relationship>,
306 L<the proxied relationship attribute|DBIx::Class::Relationship::Base/proxy>
307 and the various L<relationship
308 helpers|DBIx::Class::Manual::ResultClass/DBIx::Class::Relationship>,
309 B<except> the L<M2M helper|DBIx::Class::Relationship/many_to_many> (given its
310 effects are never reflected as C<ResultSource metadata>).
311
312 =head3 DBIC_method_is_column_accessor
313
314 This attribute is applied to all methods dynamically installed as a result of
315 invoking L<add_columns|DBIx::Class::ResultSource/add_columns>.
316
317 =head3 DBIC_method_is_inflated_column_accessor
318
319 This attribute is applied to all methods dynamically installed as a result of
320 invoking L<inflate_column|DBIx::Class::InflateColumn/inflate_column>.
321
322 =head3 DBIC_method_is_filtered_column_accessor
323
324 This attribute is applied to all methods dynamically installed as a result of
325 invoking L<filter_column|DBIx::Class::FilterColumn/filter_column>.
326
327 =head3 DBIC_method_is_*column_extra_accessor
328
329 For historical reasons any L<Class::Accessor::Grouped> accessor is generated
330 twice as C<{name}> and C<_{name}_accessor>. The second method is marked with
331 C<DBIC_method_is_*column_extra_accessor> correspondingly.
332
333 =head3 DBIC_method_is_single_relationship_accessor
334
335 This attribute is applied to all methods dynamically installed as a result of
336 invoking L<might_have|DBIx::Class::Relationship/might_have>,
337 L<has_one|DBIx::Class::Relationship/has_one> or
338 L<belongs_to|DBIx::Class::Relationship/belongs_to> (though for C<belongs_to>
339 see L<...filter_rel...|/DBIC_method_is_filter_relationship_accessor> below.
340
341 =head3 DBIC_method_is_multi_relationship_accessor
342
343 This attribute is applied to the main method dynamically installed as a result
344 of invoking L<has_many|DBIx::Class::Relationship/has_many>.
345
346 =head3 DBIC_method_is_multi_relationship_extra_accessor
347
348 This attribute is applied to the two extra methods dynamically installed as a
349 result of invoking L<has_many|DBIx::Class::Relationship/has_many>:
350 C<$relname_rs> and C<add_to_$relname>.
351
352 =head3 DBIC_method_is_filter_relationship_accessor
353
354 This attribute is applied to (legacy) methods dynamically installed as a
355 result of invoking L<belongs_to|DBIx::Class::Relationship/belongs_to> with an
356 already-existing identically named column. The method is internally
357 implemented as an L<inflated_column|/DBIC_method_is_inflated_column_accessor>
358 and is labeled with both atributes at the same time.
359
360 =head3 DBIC_method_is_filter_relationship_extra_accessor
361
362 Same as L</DBIC_method_is_*column_extra_accessor>.
363
364 =head3 DBIC_method_is_proxy_to_relationship
365
366 This attribute is applied to methods dynamically installed as a result of
367 providing L<the proxied relationship
368 attribute|DBIx::Class::Relationship::Base/proxy>.
369
370 =head3 DBIC_method_is_m2m_sugar
371
372 =head3 DBIC_method_is_m2m_sugar_with_attrs
373
374 One of the above attributes is applied to the main method dynamically
375 installed as a result of invoking
376 L<many_to_many|DBIx::Class::Relationship/many_to_many>. The C<_with_atrs> suffix
377 serves to indicate whether the user supplied any C<\%attrs> to the
378 C<many_to_many> call. There is deliberately no mechanism to retrieve the actual
379 supplied values: if you really need this functionality you would need to rely on
380 L<DBIx::Class::IntrospectableM2M>.
381
382 =head3 DBIC_method_is_extra_m2m_sugar
383
384 =head3 DBIC_method_is_extra_m2m_sugar_with_attrs
385
386 One of the above attributes is applied to the extra B<four> methods dynamically
387 installed as a result of invoking
388 L<many_to_many|DBIx::Class::Relationship/many_to_many>: C<$m2m_rs>, C<add_to_$m2m>,
389 C<remove_from_$m2m> and C<set_$m2m>.
390
391 =head1 METHODS
392
393 =head2 MODIFY_CODE_ATTRIBUTES
394
395 See L<attributes/MODIFY_type_ATTRIBUTES>.
396
397 =head2 FETCH_CODE_ATTRIBUTES
398
399 See L<attributes/FETCH_type_ATTRIBUTES>. Always returns the combination of
400 all attributes: both the free-form strings registered via the
401 L<legacy system|/_attr_cache> and the DBIC-specific ones.
402
403 =head2 VALID_DBIC_CODE_ATTRIBUTE
404
405 =over
406
407 =item Arguments: $attribute_string
408
409 =item Return Value: ( true| false )
410
411 =back
412
413 This method is invoked when processing each DBIC-specific attribute (the ones
414 starting with C<DBIC_>). An attribute is considered invalid and an exception
415 is thrown unless this method returns a C<truthy> value.
416
417 =head2 _attr_cache
418
419 =over
420
421 =item Arguments: none
422
423 =item Return Value: B<purposefully undocumented>
424
425 =back
426
427 The legacy method of retrieving attributes declared on DBIC methods
428 (L</FETCH_CODE_ATTRIBUTES> was not defined until mid-2016). This method
429 B<does not return any DBIC-specific attributes>, and is kept for backwards
430 compatibility only.
431
432 In order to query the attributes of a particular method use
433 L<attributes::get()|attributes/get> as shown in the L</SYNOPSIS>.
434
435 =head1 FURTHER QUESTIONS?
436
437 Check the list of L<additional DBIC resources|DBIx::Class/GETTING HELP/SUPPORT>.
438
439 =head1 COPYRIGHT AND LICENSE
440
441 This module is free software L<copyright|DBIx::Class/COPYRIGHT AND LICENSE>
442 by the L<DBIx::Class (DBIC) authors|DBIx::Class/AUTHORS>. You can
443 redistribute it and/or modify it under the same terms as the
444 L<DBIx::Class library|DBIx::Class/COPYRIGHT AND LICENSE>.