refactor(storage/local): simplify constructor path checks and improve typing

[joshtrichards]

• Resolves: #

Summary

• Refactors constructor for a bit more clarity and explicitness
• Refactors stat() for a bit more clarity
• Minor optimization for the temporary storage unavailability check (directly use is_dir(realpath) vs loading up $this->stat unnecessarily)
• Adds property typing
• Adjusts property names for clarity/consistency
• Adds docs
• Calls out an IStorage contract issue: many/most Local methods may throw \OCP\Files\ForbiddenException even those usually expected to return, say, false under error circumstances.
  • Many of this should probably be caught internally IMO (e.g. in $this->stat()) or, at a minimum, contract updated since consumers are expected to handle these (mostly filename blacklisting and symbolic link resolution related)

Not expected to introduce any externally visible changes in behavior.

P.S. Labeled for External Storage + Filesystem, but obviously impacts all Local storage.

TODO

• ...

Checklist

• Code is properly formatted
• Sign-off message is added to all commits
• Tests (unit, integration, api and/or acceptance) are included
• Screenshots before/after for front-end changes
• Documentation (manuals or wiki) has been updated or is not required
• Backports requested where applicable (ex: critical bugfixes)
• Labels added where applicable (ex: bug/enhancement, 3. to review, feature component)
• Milestone added for target branch/version (ex: 32.x for stable32)