Citation
extends AbstractHelper
in package
implements
TranslatorAwareInterface
Uses
TranslatorAwareTrait
Citation view helper
Tags
Interfaces, Classes, Traits and Enums
- TranslatorAwareInterface
- Lightweight translator aware marker interface (used as an alternative to \Laminas\I18n\Translator\TranslatorAwareInterface, which requires an excessive number of methods to be implemented).
Table of Contents
- $dateConverter : Converter
- Date converter
- $details : array<string|int, mixed>
- Citation details
- $driver : AbstractBase
- Record driver
- $translator : TranslatorInterface
- Translator
- $uncappedPhrases : array<string|int, string>
- List of multi-word phrases to never capitalize when using title case.
- $uncappedWords : array<string|int, string>
- List of words to never capitalize when using title case.
- __construct() : mixed
- Constructor
- __invoke() : Citation
- Store a record driver object and return this object so that the appropriate template can be rendered.
- getCitation() : string
- Retrieve a citation in a particular format
- getCitationAPA() : string
- Get APA citation.
- getCitationChicago() : string
- Get Chicago Style citation.
- getCitationMLA() : string
- Get MLA citation.
- getTranslator() : TranslatorInterface
- Get translator object.
- getTranslatorLocale() : string
- Get the locale from the translator.
- setTranslator() : TranslatorAwareInterface
- Set a translator
- translate() : string
- Translate a string (or string-castable object)
- translateWithPrefix() : string
- Translate a string (or string-castable object) using a prefix, or without the prefix if a prefixed translation is not found.
- abbreviateName() : string
- Abbreviate a first name.
- capitalizeTitle() : string
- Capitalize all words in a title, except for a few common exceptions.
- cleanNameDates() : string
- Strip the dates off the end of a name.
- extractTextDomain() : array<string|int, mixed>
- Given a translation string with or without a text domain, return an array with the raw string and the text domain separated.
- fixAbbreviatedNameLetters() : string
- Fix bad punctuation on abbreviated name letters.
- formatPrimaryMLAAuthor() : string
- Format an author name for inclusion as the first name in an MLA citation.
- formatSecondaryMLAAuthor() : string
- Format an author name for inclusion in an MLA citation (after the primary name, which gets formatted differently).
- getAPAAuthors() : array<string|int, mixed>
- Get an array of authors for an APA citation.
- getAPANumbersAndDate() : array<string|int, mixed>
- Construct volume/issue/date portion of APA citation. Returns an array with three elements: volume, issue and date (since these end up in different areas of the final citation, we don't return a single string, but since their determination is related, we need to do the work in a single function).
- getAPATitle() : string
- Get the full title for an APA citation.
- getDebugTranslation() : string
- Build a debug-mode translation
- getEdition() : string
- Get edition statement for inclusion in a citation. Shared by APA and MLA functionality.
- getMLAAuthors() : array<string|int, mixed>
- Get an array of authors for an MLA or Chicago Style citation.
- getMLANumberAndDate() : string
- Construct volume/issue/date portion of MLA or Chicago Style citation.
- getMLATitle() : string
- Get the full title for an MLA citation.
- getPageRange() : string
- Construct page range portion of citation.
- getPublisher() : string
- Get publisher information (place: name) for inclusion in a citation.
- getYear() : string
- Get the year of publication for inclusion in a citation.
- isDateRange() : bool
- Is the string a date range?
- isNameSuffix() : bool
- Is the string a valid name suffix?
- isPunctuated() : bool
- Does the string end in punctuation that we want to retain?
- prepareAuthors() : array<string|int, mixed>
- The code in this module expects authors in "Last Name, First Name" format.
- reverseName() : string
- Turn a "Last, First" name into a "First Last" name.
- sanitizeTranslationKey() : string
- Make sure there are not any illegal characters in the translation key that might prevent successful lookup in language files.
- stripPunctuation() : string
- Strip unwanted punctuation from the right side of a string.
- translateString() : string
- Get translation for a string
Properties
$dateConverter
Date converter
protected
Converter
$dateConverter
$details
Citation details
protected
array<string|int, mixed>
$details
= []
$driver
Record driver
protected
AbstractBase
$driver
$translator
Translator
protected
TranslatorInterface
$translator
= null
$uncappedPhrases
List of multi-word phrases to never capitalize when using title case.
protected
array<string|int, string>
$uncappedPhrases
= ['even if', 'if only', 'now that', 'on top of']
$uncappedWords
List of words to never capitalize when using title case.
protected
array<string|int, string>
$uncappedWords
= ['a', 'an', 'and', 'as', 'at', 'but', 'by', 'for', 'from', 'from', 'in', 'into', 'like', 'nor', 'of', 'off', 'on', 'onto', 'or', 'over', 'so', 'than', 'the', 'to', 'upon', 'via', 'with', 'yet']
Some words that were considered for this list, but excluded due to their potential ambiguity: down, near, out, past, up
Some words that were considered, but excluded because they were five or more characters in length: about, above, across, after, against, along, among, around, before, behind, below, beneath, beside, between, beyond, despite, during, except, inside, opposite, outside, round, since, through, towards, under, underneath, unlike, until, within, without
Methods
__construct()
Constructor
public
__construct(Converter $converter) : mixed
Parameters
- $converter : Converter
-
Date converter
Return values
mixed —__invoke()
Store a record driver object and return this object so that the appropriate template can be rendered.
public
__invoke(Base $driver) : Citation
Parameters
- $driver : Base
-
Record driver object.
Return values
Citation —getCitation()
Retrieve a citation in a particular format
public
getCitation(string $format) : string
Returns the citation in the format specified
Parameters
- $format : string
-
Citation format ('APA' or 'MLA')
Return values
string —Formatted citation
getCitationAPA()
Get APA citation.
public
getCitationAPA() : string
This function assigns all the necessary variables and then returns an APA citation.
Return values
string —getCitationChicago()
Get Chicago Style citation.
public
getCitationChicago() : string
This function returns a Chicago Style citation using a modified version of the MLA logic.
Return values
string —getCitationMLA()
Get MLA citation.
public
getCitationMLA([int $etAlThreshold = 2 ][, string $volNumSeparator = ', no. ' ][, string $numPrefix = ', ' ][, string $volPrefix = 'vol. ' ][, string $yearFormat = ', %s' ][, string $pageNoSeparator = ',' ][, bool $includePubPlace = false ][, string $doiPrefix = 'https://doi.org/' ][, bool $labelPageRange = true ][, bool $doiArticleComma = true ]) : string
This function assigns all the necessary variables and then returns an MLA citation. By adjusting the parameters below, it can also render a Chicago Style citation.
Parameters
- $etAlThreshold : int = 2
-
The number of authors to abbreviate with 'et al.'
- $volNumSeparator : string = ', no. '
-
String to separate volume and issue number in citation.
- $numPrefix : string = ', '
-
String to display in front of numbering
- $volPrefix : string = 'vol. '
-
String to display in front of volume
- $yearFormat : string = ', %s'
-
Format string for year display
- $pageNoSeparator : string = ','
-
Separator between date / page no.
- $includePubPlace : bool = false
-
Should we include the place of publication?
- $doiPrefix : string = 'https://doi.org/'
-
Prefix to display in front of DOI; set to false to omit DOIs.
- $labelPageRange : bool = true
-
Should we include p./pp. before page ranges?
- $doiArticleComma : bool = true
-
Should we put a comma instead of period before a DOI in an article-style citation?
Return values
string —getTranslator()
Get translator object.
public
getTranslator() : TranslatorInterface
Return values
TranslatorInterface —getTranslatorLocale()
Get the locale from the translator.
public
getTranslatorLocale([string $default = 'en' ]) : string
Parameters
- $default : string = 'en'
-
Default to use if translator absent.
Return values
string —setTranslator()
Set a translator
public
setTranslator(TranslatorInterface $translator) : TranslatorAwareInterface
Parameters
- $translator : TranslatorInterface
-
Translator
Return values
TranslatorAwareInterface —translate()
Translate a string (or string-castable object)
public
translate(string|object|array<string|int, mixed> $target[, array<string|int, mixed> $tokens = [] ][, string $default = null ][, bool $useIcuFormatter = false ][, array<string|int, string> $fallbackDomains = [] ]) : string
Parameters
- $target : string|object|array<string|int, mixed>
-
String to translate or an array of text domain and string to translate
- $tokens : array<string|int, mixed> = []
-
Tokens to inject into the translated string
- $default : string = null
-
Default value to use if no translation is found (null for no default).
- $useIcuFormatter : bool = false
-
Should we use an ICU message formatter instead of the default behavior?
- $fallbackDomains : array<string|int, string> = []
-
Text domains to check if no match is found in the domain specified in $target
Return values
string —translateWithPrefix()
Translate a string (or string-castable object) using a prefix, or without the prefix if a prefixed translation is not found.
public
translateWithPrefix(string $prefix, string|object|array<string|int, mixed> $target[, array<string|int, mixed> $tokens = [] ][, string $default = null ][, bool $useIcuFormatter = false ][, array<string|int, string> $fallbackDomains = [] ]) : string
Parameters
- $prefix : string
-
Translation key prefix
- $target : string|object|array<string|int, mixed>
-
String to translate or an array of text domain and string to translate
- $tokens : array<string|int, mixed> = []
-
Tokens to inject into the translated string
- $default : string = null
-
Default value to use if no translation is found (null for no default).
- $useIcuFormatter : bool = false
-
Should we use an ICU message formatter instead of the default behavior?
- $fallbackDomains : array<string|int, string> = []
-
Text domains to check if no match is found in the domain specified in $target
Return values
string —abbreviateName()
Abbreviate a first name.
protected
abbreviateName(string $name) : string
Parameters
- $name : string
-
The name to abbreviate
Return values
string —The abbreviated name.
capitalizeTitle()
Capitalize all words in a title, except for a few common exceptions.
protected
capitalizeTitle(string $str) : string
Parameters
- $str : string
-
Title to capitalize.
Return values
string —Capitalized title.
cleanNameDates()
Strip the dates off the end of a name.
protected
cleanNameDates(string $str) : string
Parameters
- $str : string
-
Name to clean.
Return values
string —Cleaned name.
extractTextDomain()
Given a translation string with or without a text domain, return an array with the raw string and the text domain separated.
protected
extractTextDomain(string|object|array<string|int, mixed> $target) : array<string|int, mixed>
Parameters
- $target : string|object|array<string|int, mixed>
-
String to translate or an array of text domain and string to translate
Return values
array<string|int, mixed> —fixAbbreviatedNameLetters()
Fix bad punctuation on abbreviated name letters.
protected
fixAbbreviatedNameLetters(string $str) : string
Parameters
- $str : string
-
String to fix.
Return values
string —formatPrimaryMLAAuthor()
Format an author name for inclusion as the first name in an MLA citation.
protected
formatPrimaryMLAAuthor(string $author) : string
Parameters
- $author : string
-
Name to reformat.
Return values
string —formatSecondaryMLAAuthor()
Format an author name for inclusion in an MLA citation (after the primary name, which gets formatted differently).
protected
formatSecondaryMLAAuthor(string $author) : string
Parameters
- $author : string
-
Name to reformat.
Return values
string —getAPAAuthors()
Get an array of authors for an APA citation.
protected
getAPAAuthors() : array<string|int, mixed>
Return values
array<string|int, mixed> —getAPANumbersAndDate()
Construct volume/issue/date portion of APA citation. Returns an array with three elements: volume, issue and date (since these end up in different areas of the final citation, we don't return a single string, but since their determination is related, we need to do the work in a single function).
protected
getAPANumbersAndDate() : array<string|int, mixed>
Return values
array<string|int, mixed> —getAPATitle()
Get the full title for an APA citation.
protected
getAPATitle() : string
Return values
string —getDebugTranslation()
Build a debug-mode translation
protected
getDebugTranslation(string $domain, string $str, array<string|int, mixed> $tokens) : string
Parameters
- $domain : string
-
Text domain
- $str : string
-
String to translate
- $tokens : array<string|int, mixed>
-
Tokens to inject into the translated string
Return values
string —getEdition()
Get edition statement for inclusion in a citation. Shared by APA and MLA functionality.
protected
getEdition() : string
Return values
string —getMLAAuthors()
Get an array of authors for an MLA or Chicago Style citation.
protected
getMLAAuthors([int $etAlThreshold = 2 ]) : array<string|int, mixed>
Parameters
- $etAlThreshold : int = 2
-
The number of authors to abbreviate with 'et al.' This is a major difference between MLA/Chicago Style.
Return values
array<string|int, mixed> —getMLANumberAndDate()
Construct volume/issue/date portion of MLA or Chicago Style citation.
protected
getMLANumberAndDate([string $volNumSeparator = '.' ][, string $volPrefix = '' ][, string $yearFormat = ', %s' ]) : string
Parameters
- $volNumSeparator : string = '.'
-
String to separate volume and issue number in citation (only difference between MLA/Chicago Style).
- $volPrefix : string = ''
-
String to display in front of volume
- $yearFormat : string = ', %s'
-
Format string for year display
Return values
string —getMLATitle()
Get the full title for an MLA citation.
protected
getMLATitle() : string
Return values
string —getPageRange()
Construct page range portion of citation.
protected
getPageRange() : string
Return values
string —getPublisher()
Get publisher information (place: name) for inclusion in a citation.
protected
getPublisher([bool $includePubPlace = true ]) : string
Shared by APA and MLA functionality.
Parameters
- $includePubPlace : bool = true
-
Should we include the place of publication?
Return values
string —getYear()
Get the year of publication for inclusion in a citation.
protected
getYear() : string
Shared by APA and MLA functionality.
Return values
string —isDateRange()
Is the string a date range?
protected
isDateRange(string $str) : bool
Parameters
- $str : string
-
The string to check.
Return values
bool —True if it's a date range.
isNameSuffix()
Is the string a valid name suffix?
protected
isNameSuffix(string $str) : bool
Parameters
- $str : string
-
The string to check.
Return values
bool —True if it's a name suffix.
isPunctuated()
Does the string end in punctuation that we want to retain?
protected
isPunctuated(string $string) : bool
Parameters
- $string : string
-
String to test.
Return values
bool —Does string end in punctuation?
prepareAuthors()
The code in this module expects authors in "Last Name, First Name" format.
protected
prepareAuthors(array<string|int, mixed> $authors[, bool $isCorporate = false ]) : array<string|int, mixed>
This support method (used by the main citation() method) attempts to fix any non-compliant names.
Parameters
- $authors : array<string|int, mixed>
-
Authors to process.
- $isCorporate : bool = false
-
Is this a list of corporate authors?
Return values
array<string|int, mixed> —reverseName()
Turn a "Last, First" name into a "First Last" name.
protected
reverseName(string $str) : string
Parameters
- $str : string
-
Name to reverse.
Return values
string —Reversed name.
sanitizeTranslationKey()
Make sure there are not any illegal characters in the translation key that might prevent successful lookup in language files.
protected
sanitizeTranslationKey(string $key) : string
Parameters
- $key : string
-
Key to sanitize
Return values
string —Sanitized key
stripPunctuation()
Strip unwanted punctuation from the right side of a string.
protected
stripPunctuation(string $text) : string
Parameters
- $text : string
-
Text to clean up.
Return values
string —Cleaned up text.
translateString()
Get translation for a string
protected
translateString(string $rawStr[, array<string|int, mixed> $tokens = [] ][, string $default = null ][, string $domain = 'default' ][, bool $useIcuFormatter = false ]) : string
Parameters
- $rawStr : string
-
String to translate
- $tokens : array<string|int, mixed> = []
-
Tokens to inject into the translated string
- $default : string = null
-
Default value to use if no translation is found (null for no default).
- $domain : string = 'default'
-
Text domain (omit for default)
- $useIcuFormatter : bool = false
-
Should we use an ICU message formatter instead of the default behavior?