* Add missing `ingroup` to class blocks (and remove from any file blocks)
as otherwise the file is indexed twice (e.g. in Doxygen) which makes
navigation on doc.wikimedia.org rather messy.
Remove duplicate descriptions from file blocks in favour of class
doc blocks. This reduces needless duplication and was often
incorrect or outdated, and helps make file headers more consistently
(visually) ignorable.
Ref https://gerrit.wikimedia.org/r/q/message:ingroup+is:merged
* Widen `@covers` tags in phpunit tests
Given all called methods are de-facto and liberally claimed, and
that we keep the coverage limited to the subject class, it maintains
the spirit and intent by listing the class explicitly instead.
PHPUnit offers a more precise tool when you need it (i.e. when testing
legacy monster/god classes), but for well-written code, the
class-wide tag is exactly what you want.
We lose useful coverage and waste valuable time on keeping tags
accurate through refactors (or worse, forget to do so).
Tracking tiny per-method details wastes time in realizing (and
fixing) when people inevitably don't keep them in sync, and time
lost in finding uncovered code to write tests to realize it was
already covered but "not yet claimed".
Ref https://gerrit.wikimedia.org/r/q/owner:Krinkle+is:merged+message:Widen
While at it, improve purposes and explainations of several mail-related
classes, and set `@since`:
- EmailNotification introduced in r22110 (1.11.0), git a6f6e04841,
later moved to a separate file in bf8810d6bc (Ic435bbdbb6).
- MailAddress introduced in r12082 (1.6.0, 1.5.7), git 5cfddf9a82.
- UserMailer converted to class with ::send in r26357 (1.12.0),
git 353f203ce2.
Change-Id: I1216781240bcfabdebf109cef8f995355db0f659
There are a couple of user options related classes already,
and the T321527 work on dynamic defaults is going to add
even more. Let's move them into a separate namespace
to make core a bit more organized.
Old name is kept as an alias for compatibility purposes.
Bug: T321527
Bug: T352284
Change-Id: I9822eb1553870b876d0b8a927e4e86c27d83bd52
EmailUser should distinguish between pre-checking permission, and
authorizing the sending of emails, so we can call authorizeAction()
at the appropriate time. This way, rate limits get enforced
implicitly.
This change demonstrates the motivation behind Iebd62b0487a
and I0c2ce8bdf07.
Change-Id: Ic30c36f82ab142130b5f4167c13284aeed899231
- Replace MessageLocalizer with message formatters. This is still not
very pretty, but at least now callers don't need to obtain monster
classes like RequestContext to use this service.
- Update the documentation and add a couple notes about potential future
improvements.
A subsequent patch will make the service stable for use, deprecate the
old stuff, and update the release notes.
Bug: T265541
Change-Id: Ic9b0ef7b3b410d48375836f4db565ffd46936319
- Rename methods to follow the more standard convention used for
commands.
- Update doc comments.
- Add new hooks with final method names and parameter types, to replace
the old messy hooks.
- Deprecate the remaining old hooks.
Bug: T265541
Change-Id: I609709a70fb58ce00b9f179ee4de2f6ac5e0a1cf
This is necessary so that EmailUser can behave as a command. EmailUser
now takes the performer as a constructor parameter; this, in combination
with the statelessness of the service, allows it to be reused for
multiple sends. Some BC code was also moved to the factory.
Bug: T265541
Change-Id: I2568359f00f429ef3ab3bfbfb803dc8e51cd8add
- Use UserEmailContact for the sender; internally, we still fall back to
User.
- Try to use Authority and UserIdentity instead of User where possible
- Replace PermissionManager with Authority
- Fix handling of block message in BC code for Special:EmailUser
(currently throwing a fatal because of return type mismatch, as the BC
code is not intercepting the Message object)
- Move the ratelimit check around the beginning of the method, instead
of running it after having pointlessly built half of the email body
- Stop using User::isBlockedFromEmailuser and add a TODO about
deprecating that method.
Bug: T265541
Change-Id: Icc06b816a553028d816e6ab1b43ad93605fd5b3f
- Remove getTarget(). Converting a username to a user object is not a
responsibility of this command. This logic generally belongs to
callers.
- Use Authority for the sender, as we need to perform permission checks
on them. Internally, we're still converting to User.
Bug: T265541
Change-Id: Ib0cd86d97dbf1cd97dcb316480171e4fbf4a09f4
This is non-trivial because:
- "blockedemailuser" is not a real message, so it can't be passed to
StatusValue. For now, use BlockErrorFormatter to obtain a suitable
message. In the future, we should simply rely on
Authority/PermissionManager to set a message for us, but that's left
for another change.
- The hooks used here return an error in the format accepted by
ErrorPageError. There's no "official" way to do this with StatusValue.
This patch uses StatusValue::value as a temporary workaround, but
these hooks should be replaced with a new hook that uses StatusValue
for errors.
As an aside, note that ApiEmailUser passes the return value of
getPermissionsError to dieWithError(), which doesn't work in the cases
above. This is a pre-existing issue that will be fixed in another patch.
Bug: T265541
Change-Id: I84cc521b24adef6406e0378a293438d5cd7db02a
- Make getTarget and validateTarget consistently return StatusValue, and
adjust the return value so that it includes the full error message,
without having to process the key again in callers.
- Consistently use emailnotarget instead of notargettext. This was
already the case everywhere but in submit(). I believe this was just a
mistake.
- Improve confusing reuse of variable in
SpecialEmailUser::sendEmailForm.
::getPermissionsError() is messier and will be done in another patch.
Bug: T265541
Change-Id: Ifeb081f6c1d49272ca6c67626e5a419a54653471
- Strengthen types
- Use StatusValue instead of Status
- Extract duplicated code to a new private method
- Add MailAddress::equals to compare addresses, instead of relying on
the weak '!=' comparison. There might be a question of whether having
the same address should be enough for two MailAddress objects to be
equal, but the implementation in this patch preserves the status quo.
- Make the new validateTarget accept a User object directly. This is
better than passing strings around just to have the "validator" create
a user for you.
- Avoid returning false if there's a hook error in submit(). Accepting 5
different error formats in the same hook is simply unreasonable, and
this should eventually be standardized to use StatusValue. The old
methods in SpecialEmailUser retain BC.
Bug: T265541
Change-Id: Ia0ba27fe634e328dff1a6c06fb9979cb8ce4f7e7
- Make it an actual service
- Make its methods non-static
- Adjust signatures and method calls
- Remove excessively verbose logging
- Use dependency injection
- Add unit tests
- In SpecialEmailUser, add a new non-static method to use for form
submission, and leave the old one for external callers only.
- Fix parameter type in the EmailUser hook. This was previously not
spotted by phan because the argument came from an array without
documented types.
Bug: T265541
Change-Id: I2322e9c3004d76b665d8eb8e0e4029411a01ef5a
