-
-
Notifications
You must be signed in to change notification settings - Fork 117
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add missing deprecations #222
Add missing deprecations #222
Conversation
It is more concise.
b9c0c6d
to
5d69321
Compare
Please review @sagikazarmark |
if (!isset($config['default_formatter'])) { | ||
@trigger_error(<<<'EOT' | ||
Not setting the default_formatter configuration node is deprecated since 3.x, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Well, I don't really like this kind of line splitting within strings. Does not make things easier to read IMO.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Also, maybe add error triggering in the pool as well?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Well, I don't really like this kind of line splitting within strings. Does not make things easier to read IMO.
I could argue that it is a matter of taste, but is it? I mean, you did not have to scroll horizontally to read this piece of text, so it really was easier to read in an objective way. If I didn't, the line would be ~ 130 chars wide because of indention. I don't want to end up with code like this, that must be browsed in 2 dimensions.
Also, maybe add error triggering in the pool as well?
I thought about it, but how would you achieve that? Because you can't trigger a deprecation if you don't offer a new way. Would you drop the type hinting and do duck typing? It's possible but a bit ugly. Another possiblity I thought about: make the logger mandatory too (people that do not want to log can use a null logger). If we do that, we are no longer forced to switch arguments. What do you think?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm gonna go ahead and do it while I have some spare time.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@sagikazarmark : I pushed a new commit ( 2bab6fd ) with null logger deprecated, please tell me what you think.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
ping @sagikazarmark ?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
No response. @sonata-project/contributors please review.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Using Nowdoc for this short text is to excessive.
Same for the other code fragment.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What would you do ? Concatenation? All on one line? I'll try concatenation if everyone is put off by this.
Well, I don't really like this kind of line splitting within strings. Does not make things easier to read IMO.
By that, did you mean the string the code, or the produced string? I think I might have misunderstood this.
6c46ae8
to
c7ff31a
Compare
c7ff31a
to
f54e1d4
Compare
@sagikazarmark @core23 here is version without splitting the produced string. I don't like it because I have to be careful to add the space on line 63 if I want to produce a nice string, and because it's cumbersome to create and edit (if I have to add something in the middle of the string, I have to move the point where I use concatenation). Also, notice how this would go beyond the 120 chars soft limit and make people scroll to review if I didn't use concatenation. So no, I don't think nowdoc is excessive here, but I listen when both of you say you do not like it. Complying because I want to keep the ball rolling. |
For me enforcing the char limit in every case doesn't sound like a good idea. Keep in mind that those messages are for logs or error pages, not for the code itself. Also, splitting arguments into multiple lines does not add ANY overhead, the concatenation does, even if it is negligible, but it's there for the sake of char limiting? I am definitely against it. |
@@ -39,10 +39,19 @@ class Pool | |||
*/ | |||
public function __construct(LoggerInterface $logger = null, $defaultFormatter = null) | |||
{ | |||
// NEXT_MAJOR: make both parameters required |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Do we really need a logger here? Personally I would prefer leaving it optional and using the NullLogger as a fallback so that there is no need to check the existence of the logger. I would even consider removing it from the constructor and using the LoggerAwareInterface.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I thought of it, but it makes BC harder to achieve. And anyway, this class is mostly used via the DIC imo, which makes providing the logger a non-issue. But also makes BC less an issue. Will think about it more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
So I thought about it, and I think BC might be actually achievable with some func_num_args
magic. Let me give it a try.
That's their main purpose indeed, but the message should also be reviewed, and might be edited, or just read by someone who wished to understand what the condition he just read is about.
I have zero concern about overhead here, that would be a typical case of premature performance optimization. What I want to optimize for here is readability and maintainability. I want to avoid things you can see in Symfony like this kind message I linked to earlier where you have to scroll again and again, and things you can see in Doctrine, like this kind of unmaintainable message. Heredoc was IMO made precisely for this kind of case, and if you start not using it with short cases, you can very well get carried away with long strings like in Symfony or Doctrine. That's what I want to avoid here. I can see though how heredoc / nowdoc have their own problems :
I'd like to promote them however, because the advantages show up quickly, once you go past parsing the delimiters, the enclosed message is very readable, and in a very objective and justifiable manner :
Your main point might be "one log should be equal to one line". I tend to instinctively agree with that, but can't say why. I mean, what are you going to do with that, count the number of logs? Or is it about parsing logs with ease? Anyway, it this rule is so important, shouldn't it be the concern of the logging library, which could easily strip carriage returns and extra whitespace? |
I think all arguments are given, it's up to the maintainers to decide. |
Indeed. I'm working on the LoggerAwareInterface implementation right now, almost finished. Not using heredoc because I don't want this discussion to hold this PR back. |
35b207c
to
b5e1677
Compare
' This argument will become mandatory in 4.0.', | ||
__METHOD__ | ||
), E_USER_DEPRECATED); | ||
} |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@sagikazarmark : I'm done with the LoggerAwareInterface
implementation (I think). Looks good?
@@ -34,15 +36,43 @@ class Pool | |||
protected $logger; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If you use the trait from the psr/log package you can drop this
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Scheduled for next major
} | ||
} | ||
|
||
final public function setLogger(LoggerInterface $logger) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This as well
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
will do 👍
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Oh wait, we don't have traits yet (php 5.3). Let's add a NEXT_MAJOR
tag instead.
return $this->logger; | ||
} | ||
|
||
return new NullLogger(); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hm, not sure about lazy initialization. I tend to avoid it. Also, you didn't spare anything, the same condition is still there. I would probably set a null logger in the constructor by default.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nice suggestion, I'll do that.
bd3340f
to
aa10fee
Compare
@sagikazarmark : all good now? |
|
||
// TODO: This should become a required first parameter when the major version is changed | ||
$this->logger = new NullLogger(); | ||
// NEXT_MAJOR: remove this block |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Add a new line here?
__METHOD__ | ||
), E_USER_DEPRECATED); | ||
|
||
return; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Returning here is not a good idea as the default formatter is null and we should trigger a deprecation error. Just set the defaultFormatter to null and let the rest of the logic run.
), E_USER_DEPRECATED); | ||
|
||
return; | ||
} |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Add a newline here?
|
||
return; | ||
} | ||
if (func_num_args() == 1 && $defaultFormatter instanceof LoggerInterface) { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Elseif? No need to evaluate this condition if there are two arguments.
} | ||
if (func_num_args() == 1 && $defaultFormatter instanceof LoggerInterface) { | ||
$this->logger = $defaultFormatter; | ||
@trigger_error(sprintf( |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Shouldn't this error be triggered if there are two arguments too?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe: if this->logger is set then trigger error else this->logger = new NullLogger().
* | ||
* @param LoggerInterface will be used to report errors | ||
*/ | ||
final public function setLogger(LoggerInterface $logger) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Not sure how this works in the interface/trait, but I would use the exact same signature to avoid breaking BC (though removing final is not a BC breaking operation). As far as I remember the trait exposes a fluent interface. I might be wrong, but if not, this should be fluent as well.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The interface is not fluent, and as you said, removing final is not a BC-break, but there is little point to making it final if we are sure it won't be in the future.
842eb8d
to
15134b1
Compare
@sagikazarmark : thanks for your review, I reworked the constructor entirely with your remarks in mind, hopefully the logic is better this time. |
$this->logger = new NullLogger(); | ||
} | ||
// NEXT_MAJOR: make defaultFormatter required | ||
if (is_null($defaultFormatter)) { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This issue is still not resolved: if the first and only arg is a logger, default formatter won't be null here, missing the deprecation trigger. Either check the class property, or set the default formatter on line 51 to null.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Oh right, I missed that, sorry! I'll do the former.
15134b1
to
1c2394e
Compare
@sagikazarmark : fixed the default formatter check |
{ | ||
$this->logger = $logger; | ||
if (func_num_args() == 2) { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
NEXT_MAJOR: Remove this block
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I moved the comment to line 34, to explain that line 35 must be kept, which would be harder to convey from line 45.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
yoda please
// NEXT_MAJOR: keep the else block only | ||
if ($this->logger) { | ||
@trigger_error(sprintf( | ||
'Providing a logger to %s through the constructor is deprecated since 3.x'. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This will become "Providing a logger to Pool::__construct through the constructor...". Is this intended?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is where the string split kicks in as well: if you change the message, you need to rearrange the strings as well.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Oh right, changing it to __CLASS__
This is where the string split kicks in as well: if you change the message, you need to rearrange the strings as well.
Yeah but if you used nowdoc it's a breeze: you join the lines together again, hit gqq
and you're done. If you use concatenation… that's another story.
|
||
## Deprecated unspecified Sonata\FormatterBundle\Formatter\Pool defaultFormatter | ||
|
||
Instanciating the `Sonata\FormatterBundle\Formatter\Pool` class should be done |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Instantiating
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
One of my coworkers just made this mistake this week! Now I'm contaminated!
## Deprecated specifying a logger in the Sonata\FormatterBundle\Formatter\Pool constructor | ||
|
||
Providing a logger to a `Sonata\FormatterBundle\Formatter\Pool` instance is | ||
optional, and optional dependencies should be provided through a setter. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
IMO this is arguable, I would just stick to facts: Logger can now be injected via setter instead of passing it to the constructor.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That's right, let's not make the upgrade file up to debate
default_formatter: my_formatter | ||
``` | ||
|
||
## Deprecated specifying a logger in the Sonata\FormatterBundle\Formatter\Pool constructor |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe say injecting?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That's better, yes 👍
|
||
Before: | ||
|
||
``` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Missing php?
$pool->setLogger($myLogger); | ||
``` | ||
|
||
## Deprecated unspecified Sonata\FormatterBundle\Formatter\Pool defaultFormatter |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Deprecated unspecified default formatter in Sonata\FormatterBundle\Formatter\Pool constructor?
## Deprecated unspecified Sonata\FormatterBundle\Formatter\Pool defaultFormatter | ||
|
||
Instanciating the `Sonata\FormatterBundle\Formatter\Pool` class should be done | ||
with both a `$defaultFormatter` argument. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
-both
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Good catch!
Added a few more comments, but the code looks ok to me. |
1c2394e
to
54194d0
Compare
Hurray! @sonata-project/contributors , can you please give this a final review? |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Apart from how exception messages are handled I approve. It should be up to the maintainers to decide if messages should be split, I am definitely against it.
use Twig_Environment; | ||
use Twig_Error_Syntax; | ||
use Twig_Sandbox_SecurityError; | ||
|
||
class Pool | ||
class Pool implements LoggerAwareInterface |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
this is per definition a BC break IMO
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't think so. Please tell me how it would be one.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I am curious about the reasoning as well. 😄
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
thats why i said per definition, but if we fullfill the interface, everything is fine.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just for the theoretical debate: how is it a BC break per definition? If you don't actually implement the interface your code will be broken.
list($logger, $defaultFormatter) = func_get_args(); | ||
$this->logger = $logger; | ||
$this->defaultFormatter = $defaultFormatter; | ||
} elseif (func_num_args() == 1) { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
yoda please
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You can't assign a value to a function call. So this would protect us from nothing, and make things less readable.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just wanted to say that. Yoda for function call?????
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@sagikazarmark : I always said the Jedi council has too much influence :) Look how carried away they can get
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Well, for me THIS is the point where sanity should be superior to consistency.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ok, how you like, I really like the reading more
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah but then again you guys put verbs at the end of a sentence 🇩🇪 ;)
{ | ||
$this->logger = $logger; | ||
if (func_num_args() == 2) { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
yoda please
if ($this->logger) { | ||
@trigger_error(sprintf( | ||
'Providing a logger to %s through the constructor is deprecated since 3.x'. | ||
' and we no longer be possible in 4.0'. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
we or will?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
will :P
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@OskarStark fixed! Good catch!
This will allows us to avoid having to switch arguments when making the default formatter mandatory, thus getting a good upgrade path through the deprecation system. If no logger is provided, a NullLogger is used.
This can be used by tools like Sentry to display a nice stack trace.
54194d0
to
32b654b
Compare
Thanks @OskarStark , @core23, final review and merge? Or maybe we can merge like that since @sagikazarmark has approved? |
I still have faith that @core23 will veto the string splitting. |
Noooooo! Please don't do that! I already abandoned nowdoc because you asked, please don't coerce me into commiting any other atrocity. Plus, the produced string isn't split, isn't this what you wanted? @sagikazarmark joking aside, I'd like to know :
|
Whoa, too much questions and logical links between them. I think I already expressed that exception messages are NOT primarily for developers to read (or at least not as part of the code, but in logs or on error pages), while code needs to be read, so char limit makes sense there. I also said that any kind of string magic adds an overhead, even if negligible. Anything like that JUST FOR readability is totally unacceptable IMO. Most IDEs break the long lines automatically anyway, so the readability issue is not an issue then. Char limit is not for string literals, it's for code. How do you apply char limit to a JSON document for example? The only reason you can do it here is that you can do it programatically. GOTO two points above In the linked doctrine case I would probably use sprintf, since they mostly use concatenation because of the parameters in the string. This is also a thing where sanity should be over consistency: you cannot apply a char limit anywhere, or you can, but it comes with a price which I don't want to pay. I think enough reasons and arguments said, while on the other side I only see blindly applying char limit (no offense) and bringing the readability argument which I IMO is not a valid one (see reasoning above). |
I numbered them!
Primarily. Still, it can be helpful for them. In our case, I think it clarifies a lot of things. So yes, char limit makes sense there too IMO, and makes sense in any file that is considered code (as opposed to data). But maybe that's where the argument boils down to? You view exception messages as pure data, while I think of them more as metadata associated with a piece of code.
I don't store JSON documents in code directly… that's data, not code.
Nowdoc doesn't add any, does it?
No offense taken, I'm happy with this dicussion, and hope you are too. I know it's a very pedantic debate, but it affects a lot of code. |
Well, that's why I said it's a matter of priorities and personal taste and should be up to the maintainers to decide. I don't actually think that any of our reasoning can be superior to each other. One thing I would keep in mind: consistency with the rest of the code base is important too, so if you want to raise this issue, I would be happier with a general one for all the projects. |
I'll make sure to do that and ping you when I do. In the meantime, I think we can merge this as is b/c we already use concatenation and heredoc in Sonata for that purpose (guess who did this). The contributing guide even shows concatenation. |
Bah, abominations slip in unnoticed is a downside of open source projects. |
if (!isset($config['default_formatter'])) { | ||
@trigger_error( | ||
'Not setting the default_formatter configuration node is deprecated since 3.x,'. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I wouldn't split this string in two parts just for the character limit, because searching for this particular string in the whole projects wouldn't work later.
This is a general discussion I don't want to start
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
So diplomatic.... 😝
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is a general discussion I don't want to start
Well why are you starting it then? All jokes aside, you both aprroved, so I'll just merge. But stay tuned for a real discussion about this, I'll make a blog post an issue soon.
I am targetting this branch, because this is BC (addind a deprecation notice).
Changelog
Subject
See #221