Issue #2971050 by railgun, ao2, james.williams, Anybody: Provide an option to get language fallback candidates

Using $this->t() in Object Oriented code is considered a good practice.

Mitesh Patel authored Jun 06, 2017 and Antonio Ospite committed Jun 06, 2017

In PHP 5 using type hints in function signatures for primitive types is
only allowed when the default value is NULL, otherwise there are errors
like the following:

  PHP Fatal error:  Default value for parameters with a class type hint
  can only be NULL in .../select_translation/select_translation.module

So don't use type hinting for string parameters to keep compatibility
with PHP 5.

This makes it clearer that the specified priorities depend on the
selection and are not a standalone setting.

Use more precise descriptions, and use bullet lists to highlight
alternatives.

Using '#states' is the preferred mechanism for Drupal 8.

Use the 'enabled' state instead of the 'visible' state because this way
the UI does not change drastically, and the user has a more predictable
experience.

Make it a clearer that the only one node is returned from
select_translation_of_node().

The automated testing infrastructure pointed out these coding standard
violations.

line 19  Expected "array" but found "Array" for function return type
     59  Parameter tags must be grouped together in a doc comment
     75  Whitespace found at end of line
     81  Data types in @return tags need to be fully namespaced

And while fixing them, also move the explanation of the mode value
outside of the @param tag group so that it can have empty lines and be
more readable.

Clarify what the assumptions of the option are.

In the code relative to the option
'include_content_with_unpublished_translation' split the AND condition
definition from its usage to improve readability.

Factor out a select_translation_parse_mode() function which can be
shared with the Views filter.

This is only a cosmetic change to reflect how the Views filter processes
the mode parameter. This makes the UI documentation and the API
documentation more aligned.

The old code was using the name $mode for two different things: the
string parameter passed to the function and the corresponding array of
languages.

Use the name $lang_list for the second one: it reflects better the
meaning of the variable.

Make it clearer that 'current' refers to the interface language and
'default' refers to the _site_ default language.

If the language code list is going to contain only one element, like in
the case of the 'default_language_only' option, just use the actual
default language and not the placeholder.

This allows to move the code which walks the array to replace 'current'
and 'default' inside the conditional block below, making it look a lot
like what is done in select_translation.module.

This is in preparation for some changes to share some code between the
Views filter and the select_translation_of_node() API call.

To minimize the changes, during the port to drupal 8 the signature of
node_access_join() was left unchanged even if the $join variable had
really become an output only parameter, instead of an input/output one.

So make node_access_join return the JoinPluginBase object directly and
drop the $join function argument.

While at it, also rename node_access_join() to nodeAccessJoin()
following the coding standard rules.

These changes fixes two phpcs errors in one go.

FILE: ...select_translation/src/Plugin/views/filter/SelectTranslation.php
----------------------------------------------------------------------
FOUND 2 ERRORS AFFECTING 1 LINE
----------------------------------------------------------------------
 234 | ERROR | Type hint "views_join" missing for $join
 234 | ERROR | Private method name
     |       | "SelectTranslation::node_access_join" is not in
     |       | lowerCamel format
----------------------------------------------------------------------

The previous code was splitting the check on the original language in
two separate conditional blocks with the condition one the reverse of
the other, it was also using the $add_new_join flag to check if the
exclude criteria needed to be added;

However, by anticipating the application of the exclude criteria, the
two conditional block mentioned above can be merged and the code can be
simplified a lot.

With the new code, the order of some conditions in the same AND group
changes, but the final query is functionally equivalent to the previous
one.

Equality conditions are exactly what Condition::condition() is there
for, use it instead of open coding the WHERE condition which is more
error prone and can have a non-standard look into the final query.