New to CakePHP 3.3. I looked across multiple sites (Stack Overflow, W3Schools, etc.) but cannot find an answer to:
What does this piece of code mean/do in a CakePHP tutorial:
public function initialize (array $config)
1) public: I understand this can either be public, private, or protected
2) function: Is this creating a function called "initialize()"?
3) initialize(): I understand this is a method built into CakePHP, but what does it do?
4) array $config: Are these two words combined or are they separate of each other? Why do I need both words, what is the influence of one on the other?
Background: This comes from the CakePHP tutorial and is found in multiple .php files. Not sure what is php code and what is unique CakePHP terminology.
I think This is very good question...!!! This question is applied for all framework not bounded only for CakePHP.
function my_function(array $arr, int $int, $bool $active)
{
/// function body
}
In technical it knows as Type Hinting
Type declarations allow functions to require that parameters are of a
certain type at call time. If the given value is of the incorrect
type, then an error is generated: in PHP 5, this will be a recoverable
fatal error, while PHP 7 will throw a TypeError exception.
To specify a type declaration, the type name should be added before
the parameter name. The declaration can be made to accept NULL values
if the default value of the parameter is set to NULL.
Check about valid types paramater
Reference: http://php.net/manual/en/functions.arguments.php
I see at least one great advantage of using type hinting: readability. It's easier to see what kind of parameter a function/method expects.
Some will see this as a drawback that if you don't respect a type hint and pass some not-type-valid parameter, you'll get a catchable fatal error. However,
I personally think it forces the developer to respect your interfaces more
It allows your code to just work with the received parameters.
The generated error is catchable.
Question of Performance?
Making the decision of using type hints or not using type hints should not be the result of performances considerations. You should use or not use the feature.
Even if there is some performance impact, it should be pretty minimal. I would say there are many parts of your code that you should optimize before considering this.
Conclusion
In conclusion, a personal opinion: I quite often use those type hints, just so:
Other Developers using my code know what they are expected to pass in (they don't always read the documentation...)
If they don't do what is expected, it fails; hard; in a way they immediately notice
My code doesn't have to check if the received parameter is of the right type: I know it is, as PHP enforces that for me.
Related
Using the following reflection on built in functions, makes the return type always be null.
$reflectionFunction = new \ReflectionFunction('strtoupper');
// $reflectionFunction->getReturnType() returns null
While getDocComment does not work, how to get the return type of built in functions. I know this is expected, as the documentation describes. It is a question about how to proceed from here, to calculate the return type.
Unfortunately you have to use a map for this, PHPStan has a decent one that you could lean on: Phpstans Version
It's originally derived from this one from Phan version.
I don't think either is available as separate packages so you might have to depend on the full project, or do what PHPStan did an make and maintain your own copy. You could also talk to them about spinning it off in to a separate package. The good news is that it is really simple to use, see the helper classes in the same folder as the files.
Should I type hint everything (parameters and return values) whenever possible? And maybe even strive to write code that can be type hinted? In the real world with real developers which may or may not be less than stellar is there any drawback to type hinting whenever possible?
In my mind, code that breaks fast and furious is one that breaks before it can enter production most of the time.
Type hinting is the way to go. I would start with type hinting arguments (combined with interfaces), return values, and whenever you initialize a variable or property. Combined with doc blocks, and you have just documented your code in a way that allows others to pickup quickly.
function getValue(\Settings\Bar $foo) : string
{
$val = (string) $foo->value;
//..
return $val;
}
$myVal = (string) getValue($bar);
If anyone makes a mistake, the debugger will pinpoint you the exact location. Moreover use
declare(strict_types=1);
at the top of all your php pages to enforce type hinting and you are on your way to write enterprise level code using PHP.
Type hinting helps other developers or even you to understand the code better without deep diving into it. You don't have to understand internal logic of a class or a function, or search a manual or the Internet to know the type of a value that this or that function returns.
It also helps to prevent one from making silly errors. For example, one thinks that a function accepts an ArrayAccess object, but in reality, the function accepts just arrays which might cause an error.
The only drawback I can see is that it's hard to maintain type hinting and keep everything consistent due to nature of PHP itself.
So, it's heavily recommended to do type hinting whenever it's possible. With modern IDEs like PHPStorm it becomes pretty easy to maintain type hinting and keep it up to date and consistent.
Working through several layers of an MVC architecture designed program, I find that I would like to have more information on a deeper layer's method return result, and that it's not always that I can anticipate when I'll need this information. And - for abstraction sake - I might not want that method outputting stuff to the application-specific log (that method could be used in a different program), or have a specific application dependent behaviour like other layers above.
For instance, in a given utility function I might have several pre-requisite checks before executing an action, that fail. If I return false on any of them, the caller doesn't know what happened. If I return false and log to the application log what happened, I'm bounding that function to application specific behaviour.
Question is: is it good/common pratice to implement a little class called MyResult and have it return the response status (ok/false), a message, an eventual integer code, and an object placeholder (array or object) where the caller could access the returned object? This MyResult class would be used throughout the whole system and would be a common "dialect" between all methods and their callers. All methods would then return an instance of MyResult, all the times.
Could you give an example? It seems a bit, but I can be mistaken, that you are having methods you are using statically (even if they are not implemented/called like that they could've been). The basic example of the table-object that can paint itself is called like so: $myTable->paint();. It can return a variable if it worked or not (true/false) but any other thing (like logging) is a function of table() and neither your calling method, nor the return value should have anything to do with that as far as I'm concerned.
Maybe I'm having a hard time understanding what situation you are going to use this for, but if you want to send messages around for some purpose that requires messages (or events etc) you should define those, but I don't see any merit in defining a default returnObject to pass around method-call results.
For errors you have two options: exceptions (that is: things you really don't expect to happen and should halt execution) and errors: expected but unwanted behaviour. The first should be left alone, the second can be tricky, but I'd say the object itself should contain a state which makes it clear what happened.
That's what exceptions are for. You don't have to over-do them like Java, but they exist because error codes suck.
If a framework does not offer a specific feature you need, there is no other way then that you take care on your own. Especially if you need something that runs cross the aims of the framework, so would never make it in.
However, many frameworks offer places in which you can extend them. Some are more flexible than others. So if possible I would look if you can still implement your needed feature as a type of add-on, plugin or helper code that can stay within the frameworks terrain.
If that is not possible, I would say it's always valid to do whatever you want to do. Use the part of the framework that is useful for you.
I prefer coding standards to be logical. This is my argument for why the following set of standards are not.
I need to know one of two things: (1) why I'm wrong, or (2) how to convince my team to change them.
camelCase: Functions, class names, methods, and variables must be camelCase.
Makes it hard to differentiate between variables and classes
Goes against PHP's lowercase/underscored variables/functions and UpperCamelCase classes
Example:
$customerServiceBillingInstance = new customerServiceBillingInstance(); // theirs
$customer_service_billing_instance = new CustomerServiceBillingInstance();
Functions/methods must always return a value (and returned values must always be stored).
This appears on hundreds of our php pages:
$equipmentList = new equipmentList();
$success = $equipmentList->loadFromDatabase(true, '');
$success = $equipmentList->setCustomerList();
$success = $equipmentList->setServerList();
$success = $equipmentList->setObjectList();
$success = $equipmentList->setOwnerList();
$success = $equipmentList->setAccessList();
The return value is rarely used but always stored. It encourages the use of copy-and-paste.
No static methods
Lines like the following appear thousands of times in the codebase:
$equipmentList = new equipmentList();
$success = $equipmentList->loadFromDatabase();
I would prefer:
$equipmentList = equipmentList::load();
What reason is there to not use static methods or properties? Aren't static methods responsible for non-instance-specific logic? Like initializing or populating a new instance?
Your code is not OOP unless everything returns an object
There's a piece of code that performs a query, checks it several ways for errors, and then processes the resulting array. It is repeated (copied+pasted) several times, so I put it in the base class. Then I was told returning an array is not OOP.
How do you defend these practices? I really do need to know. I feel like I'm taking crazy pills.
If you can't defend them, how do you convince the adamant author they need to be changed?
I would suggest trying to list down the goals of your coding standards, and weigh them down depending on which goals is the most important and which goals are less important.
PS: I don't speak PHP, so some of these arguments may contain blatantly incorrect PHP code.
camelCase: Functions, class names, methods, and variables must be camelCase.
Workplace's Apparent Reason: "consistency" at the cost of "information density in name".
Argument:
1) Since 'new' keyword should always be followed by a class, then you can easily spot illegal instantiation, e.g.:
$value = new functionName();
$value = new local_variable();
$value = new GLOBAL_VARIABLE();
would raise an alarm, because 'new' should be followed by a TitleCase name.
$value = new MyClass(); // correct
Relying on Case makes it easy to spot these errors.
3) Only functions can be called, you can never call variables. By relying on Case Rule, then we can easily spot fishy function calls like:
$value = $inst->ClassName();
$value = $inst->instance_variable();
$value = $GLOBAL_VARIABLE();
3) Assigning to a function name and global variables is a huge deal, since they often lead to behavior that is difficult to follow. That's why any statement that looks like:
$GLOBAL = $value;
$someFunction = $anotherFunction;
should be heavily scrutinized. Using Case Rule, it is easy to spot these potential problem lines.
While the exact Case Rule may vary, it is a good idea to have different Case Rule for each different type of names.
Functions/methods must always return a value (and returned values must always be stored).
Workplace's Apparent Reason: apparently another rule born out of blind consistency. The advantage is that every line of code that isn't a flow control (e.g. looping, conditionals) is an assignment.
Argument:
1) Mandatory assignment makes unnecessary long lines, which harms readability since it increases the amount of irrelevant information on screen.
2) Code is slightly slower as every function call will involve two unnecessary operation: value return and assignment.
Better Convention:
Learn from functional programming paradigm. Make a distinction between "subroutine" and "functions". A subroutine does all of its works by side-effect and does not return a value, and therefore its return value never need to be stored anywhere (subroutine should not return error code; use exception if it is really necessary). A function must not have any side-effect, and therefore its return value must be used immediately (either for further calculations or stored somewhere). By having side-effect free function policy, it is a waste of processor cycle to call a function and ignoring its return value; and the line can therefore be removed.
So, there is three type of correct calls:
mySubroutine(arg); // subroutine, no need to check return value
$v = myFunction(arg); // return value is stored
if (myFunction(arg)) { ... } // return value used immediately
you should never have, for example:
$v = mySubroutine(arg); // subroutine should never have a return value!
myFunction(arg); // there is no point calling side-effect free function and ignoring its return value
and they should raise warning. You can even create a naming rule to differentiate between subroutine and functions to make it even easier to spot these errors.
Specifically disallow having a "functiroutine" monster that have both a side-effect and return value.
No static methods
Workplace Apparent Reason: probably someone read somewhere that static is evil, and followed blindly without really doing any critical evaluation of its advantages and disadvantages
Better Convention:
Static methods should be stateless (no modifying global state). Static methods should be a function, not subroutine since it is easier to test a side-effect-free function than to test the side-effects of a subroutine. Static method should be small (~4 lines max) and should be self-contained (i.e. should not call too many other static methods too deeply). Most static methods should live in the Utility class; notable exceptions to this is Class Factories. Exceptions to this convention is allowed, but should be heavily scrutinized beforehand.
Your code is not OOP unless everything returns an object
Workplace Apparent Reason: flawed understanding of what is OOP.
Argument:
Fundamental datatypes is conceptually also an object even if a language's fundamental datatype doesn't inherit from their Object class.
If you can't defend them, how do you
convince the adamant author they need
to be changed?
By giving strong/valid arguments! Still I think you should only change them when your arguments are really strong! Because most of the programmers at work are used to these coding standards which is a big point why to use them.
==
Like others told before this is pretty subjective, but these are mine opinions/arguments.
1. camelCase: Functions, class names, methods, and variables must be camelCase.
I would use the PHP style if I code in PHP and the Camelcase style if I code in Java. But it does not matter which style you choose as long as you stay consistent.
2. Functions/methods must always return a value (and returned values must always be stored).
This is nonsense in my opinion. In almost all programming languages you have some sort of 'void' type. But from a testing point of view most of the times it is useful if your function are side effect free. I don't agree that your production code should always use the return value especially if it does not have any use.
3. No static methods
I would advice you to read static methods are death to testability from misko
During the instantiation I wire the
dependencies with mocks/friendlies
which replace the real dependencies.
With procedural programing there is
nothing to “wire” since there are no
objects, the code and data are
separate.
Although PHP is a dynamic language so it is not really a big problem. Still the latest PHP does support typing so that I still think most of times static methods are bad.
4. Your code is not OOP unless everything returns an object
I believe(not 100% sure) a truly OOP language should do this(return an object), but I don't agree with this like a of like languages like for example Java(which I believe is not trully OOP). A lot of the times your methods should just return primitives like String/Int/Array/etc. When you are copying and pasting a lot of code it should be a sign that something is not totally right with your design. You should refactor it(but first have a tests(TDD) ready so that you don't break any code).
Many of these coding standards are very subjective, but some important things to consider are:
Get a single set of code naming and style rules, and follow them. If you don't have already defined rules, make sure to get rules figured out. Then work at refactoring the code to follow them. This is an important step in order to make it easier for new developers to jump on board, and keep the coding consistent among developers.
It takes time and effort to change the coding standards your company puts in place. Any change to the rules means that the code really has to be gone through again to update everything to be consistent with the new standards.
Keeping the above in mind, and looking more along the lines of specific PHP coding standards. The first thing to look at is if your company uses any sort of framework, look at the coding standards for that framework as you may want to stick with those in order to stay consistent across all the code. I have listed links to a couple of the popular PHP frameworks below:
Zend Framework Naming Conventions and Zend Framework Code Style
Pear Code Standards
My personal preference in regards to your specific coding styles:
1. camelCase: Functions, class names, methods, and variables must be camelCase
Class names should be Pascal Case (Upper Camel Case).
So in your example:
class CustomerServiceBillingInstance
{
// Your class code here
}
Variables and functions I generally feel should be camel case.
So either one of these, depending on your preference in terms of underscores:
$customerServiceBillingInstance = whatever;
$customer_service_billing_instance = whatever;
2. Functions/methods must always return a value (and returned values must always be stored).
This one seems like extra code and like you could end up using extra resources. If a function doesn't need to return anything, don't return anything. Likewise, if you do not care about what a function returns, don't store it. There is no point in using the extra memory to store something you are never going to look at.
An interesting thing you may want to try on this one, is running some benchmarks. See if it takes extra time to return something and store it even though you are not looking at it.
3. Your code is not OOP unless everything returns an object
In this instance, I feel you have to draw the line somewhere. Performance wise, it is faster for you to do:
return false;
Than to do:
return new Boolean(false); // This would use up unnecessary resources but not add very much to readability or maintainability in my opinion.
Defending a coding standard
To defend a coding standard that you feel is right (or showing why another is not as good), you really are going to have to bring up one of two points.
Performance. If you can show that a particular coding standard is adversely affecting performance, you may want to consider switching.
Maintainability/Readability. Your code should be easy to read/understand.
The goal is to find the happy median between performance and the maintainability/readability. Sometimes it is an easy decision because the most maintainable option is also the best performing, other times there is a harder choice to be made.
Standards and conventions exist for many reasons, but most of these reasons boil down to "they make code easier to write and maintain." Instead of asking "is this the correct way to do X?" just cut right to the chase and ask if this criterion is met. The last point in particular is simply a matter of definition. OOP is a means, not an end.
Many of those are matters of taste. You can argue for or against camelCase all day.
However, the storing of return values that are never used is Wrong. There is no value to the code. The code is not executed. You might as well sprinkle $foo = 47 * 3; around the code.
Any code that is not doing something useful must be removed.
The bigger issue is, if you're working for a clueless manager, it may be time to move.
The one aspect of this that I don't see anybody else commenting on is the "2. Functions/methods must always return a value (and returned values must always be stored)."
If you're not using exceptions, then any function that can fail does have to return a value. The last clause is misworded; return values don't always need to be STORED, but they do always need to be CHECKED. Again, that's IF you're not using exceptions, which isn't common these days, but it's still worth mentioning.
As far as I know quite a few of the conventions you posted are encouraged by the Zend PHP Framework as well. You're not alone, I'm a Codeigniter user and my work is pretty big on using Zend Framework. These kind of naming conventions are absolutely ridiculous and I honestly can only see an advantage of using camelCase for variable names, not function names as it makes things confusing.
Read this: http://framework.zend.com/manual/en/coding-standard.naming-conventions.html
Do these coding conventions look familiar to you?
I work in php, and the concept of interfaces seems to me a little useless here. From reading, I understand that interfaces are part of "design by contract", but without at least guaranteeing a return of a type of a particular kind, there really isn't any contract. It seems it's like a contract that reads, "We agree to do the following: '' " -- there are no terms of the agreement.
If I want a guarantee that an object has a method, it doesn't seem like interfaces are particularly useful. If I try to call a method that an object doesn't have, I get a Fatal Error, so I find out pretty quickly that that class doesn't have a method with that name. If I want to be smart and check beforehand whether a class has a method, then checking the interface, and seeing whether the object implements that interface doesn't seem to save me any more time than just checking that object directly ( which I would do anyways to see if the class had that method regardless of any interfaces it did or didn't implement).
In other words, just because I have a set of methods that have particular names, that doesn't guarantee me any particular behavior. If I'm guaranteed a return of a variable of a certain type, I at least have some inkling of what the output would be, and I can write code that uses an object with that interface, because I know what I'm getting out of it. If it returns a string, I can continue coding with at least the certainty that I'm dealing with a string output afterward. So I'm guaranteed at least some behavior when a return type is specified. Is guaranteeing behavior part of what interfaces are for, or no?
The only thing I can think of is that when I'm writing code, it serves as a post-it note to myself to be sure to create certain methods when writing that class later on. It seems more like scaffolding for when I'm writing the code; I don't see much benefit from when I'm actually using it. So it's more for me to keep the standard when I'm creating classes than when I'm writing them. This benefit doesn't really seem to be captured in the concept of design by contract.
What benefit(s) do you actually get from using an interface in dynamic/loose-typed languages like PHP? Are they great, or is it something that more robust OO languages implement, so PHP implements it also?
Interfaces are used when you actually expect an object to implement a method.
For example, if I'm building a DB wrapper and it supports behaviours, which you register yourself in a bootstrap, then before running your behaviours (for example, sluggable), I will check that they implement my "DB_Wrapper_Behaviour_Interface" by using:
if(!($behaviourObject instanceof DB_Wrapper_Behaviour_Interface)) {
throw new Exception("Your behaviour doesn't implement my interface");
}
Design by contract is made more difficult without return types, but don't forget to favour 'tell' over 'ask'.
I believe an interface to be something like a responsibility. You are coding and need a collaborator. You ask it to do something because the code you are working on can't do everything. So you're asking another object to do something. An interface guarantees that the collaborator will do the job, but hides the 'how' it's done part.
Now you could argue that there's no need for the formal contract here, since the system will throw an error anyway if the collaborator can't do what you're asking it to do. But I think that misses the point in using interfaces as a responsibility.
Getting a fatal error is not always "easy". Sometimes you have to go on a specific module/action to see that something is actually missing in your class.
The interface enables you to make sure every method is implemented and to document these method (what the parameters are exactly going to be, what the return values should look like). This is useful if the parameters/values are arrays with a particular structure and you don't want to use classes instead (for the sake of simplicty).
I want to note, that PHP 5.4 will support type hinting. Right now I think there is only type hinting for function arguments, but I suppose there will be for return values, too. (At least there already is an RFC, though a very old and outdated one.)