• This site uses cookies. By continuing to use this site, you are agreeing to our use of cookies. Learn more.

Fixed Class @property phpdocs for magic methods/properties

Affected version
2.0 DP10

Xon

Well-known member
#1
Any chance the entities could be anointed with @property phpdocs so all the various magic methods show up via various IDE's auto-complete?

This is likely a large, but simple, task.
 

DragonByte Tech

Well-known member
#2
Any chance the entities could be anointed with @property phpdocs so all the various magic methods show up via various IDE's auto-complete?

This is likely a large, but simple, task.
I'd like to learn how to do this for my projects as well, if nothing else for my own sanity when using VSCode, do you have any resources for the correct way to implement this?


Fillip
 

Xon

Well-known member
#3

DragonByte Tech

Well-known member
#4
Sorry, that isn't very clear to me, being unfamiliar with this sort of thing :)

Do you mean to say that if I have an entity with a getTitle() function, I should add @property string $title to the top docblock?


Fillip
 

Chris D

XenForo developer
Staff member
#6
A good example to look at is the XF\Widget\Entity class where we've type hinted a known column (options), a getter (handler) and a relation (WidgetDefinition).

Honestly, if it's a manual job, I can't see us doing it as it isn't a great use of time right now. Also, I wouldn't go as far as to call this a bug either; pretty much the exact definition of a feature request.

It's possible we could write something to generate these automatically and for that reason we'll leave this open for now, but it likely won't be considered a priority and don't necessarily be surprised if it eventually gets moved to Suggestions.
 

Liam W

Well-known member
#8
@Chris D @Kier

I was bored, so I made a Cli command that auto-generates them. Seems to work.

Created this for the User entity:

PHP:
/**
 * @property int $user_id
 * @property string $username
 * @property string $email
 * @property int $style_id
 * @property int $language_id
 * @property string $timezone
 * @property bool $visible
 * @property bool $activity_visible
 * @property int $user_group_id
 * @property array $secondary_group_ids
 * @property int $display_style_group_id
 * @property int $permission_combination_id
 * @property int $message_count
 * @property int $alerts_unread
 * @property int $conversations_unread
 * @property int $register_date
 * @property int $last_activity
 * @property int $trophy_points
 * @property int $avatar_date
 * @property int $avatar_width
 * @property int $avatar_height
 * @property bool $avatar_highdpi
 * @property string $gravatar
 * @property string $user_state
 * @property bool $is_moderator
 * @property bool $is_admin
 * @property bool $is_staff
 * @property bool $is_banned
 * @property int $like_count
 * @property string $custom_title
 * @property int $warning_points
 * @property string $secret_key
 * @property int $xfrm_resource_count
 * @property int $xfmg_album_count
 * @property int $xfmg_media_count
 * @property int $xfmg_media_quota
 * @property string $vanity_name
 * @property int $liamw_threadsolutions_solution_count

 * @property mixed PermissionSet
 * @property mixed is_super_admin
 * @property mixed email_confirm_key
 * @property mixed warning_count

 * @property \XF\Entity\Admin Admin
 * @property \XF\Entity\UserAuth Auth
 * @property \XF\Entity\UserConnectedAccount ConnectedAccounts
 * @property \XF\Entity\UserOption Option
 * @property \XF\Entity\PermissionCombination PermissionCombination
 * @property \XF\Entity\UserProfile Profile
 * @property \XF\Entity\UserPrivacy Privacy
 * @property \XF\Entity\UserBan Ban
 * @property \XF\Entity\UserReject Reject
 * @property \XF\Entity\SessionActivity Activity
 * @property \XF\Entity\ApprovalQueue ApprovalQueue
 * @property \XF\Entity\UserFollow Following
*/
Feel free to use it for core development (and maybe stick it in the core).

Liam
 

Attachments

Chris D

XenForo developer
Staff member
#9
I was bored last night too...
PHP:
/**
 * COLUMNS
 * @property int|null $user_id
 * @property string $username
 * @property string $email
 * @property int $style_id
 * @property int $language_id
 * @property string $timezone
 * @property bool $visible
 * @property bool $activity_visible
 * @property int $user_group_id
 * @property array $secondary_group_ids
 * @property int $display_style_group_id
 * @property int $permission_combination_id
 * @property int $message_count
 * @property int $alerts_unread
 * @property int $conversations_unread
 * @property int $register_date
 * @property int $last_activity
 * @property int $trophy_points
 * @property int $avatar_date
 * @property int $avatar_width
 * @property int $avatar_height
 * @property bool $avatar_highdpi
 * @property string $gravatar
 * @property string $user_state
 * @property bool $is_moderator
 * @property bool $is_admin
 * @property bool $is_staff
 * @property bool $is_banned
 * @property int $like_count
 * @property string $custom_title
 * @property int $warning_points
 * @property string $secret_key
 * @property int $permission_combination_id_
 * @property int $last_activity_
 *
 * GETTERS
 * @property \XF\PermissionSet $PermissionSet
 * @property bool $is_super_admin
 * @property string $email_confirm_key
 * @property int $warning_count
 *
 * RELATIONS
 * @property \XF\Entity\Admin $Admin
 * @property \XF\Entity\UserAuth $Auth
 * @property \XF\Entity\UserConnectedAccount[] $ConnectedAccounts
 * @property \XF\Entity\UserOption $Option
 * @property \XF\Entity\PermissionCombination $PermissionCombination
 * @property \XF\Entity\UserProfile $Profile
 * @property \XF\Entity\UserPrivacy $Privacy
 * @property \XF\Entity\UserBan $Ban
 * @property \XF\Entity\UserReject $Reject
 * @property \XF\Entity\SessionActivity $Activity
 * @property \XF\Entity\ApprovalQueue $ApprovalQueue
 * @property \XF\Entity\UserFollow[] $Following
 */
Obviously this was an open bug report so until we say otherwise there's every danger that we'd have implemented it (which we have for the next release).

You may still want to use your own version, though. Ours, by design, only adds class properties for the structure of the original class (so it bypasses structure extensions). There's a few other improvements in that it attempts to type hint getter function types and maintains the original column type if a getter overlaps it.
 

Liam W

Well-known member
#10
I was bored last night too...
PHP:
/**
* COLUMNS
* @property int|null $user_id
* @property string $username
* @property string $email
* @property int $style_id
* @property int $language_id
* @property string $timezone
* @property bool $visible
* @property bool $activity_visible
* @property int $user_group_id
* @property array $secondary_group_ids
* @property int $display_style_group_id
* @property int $permission_combination_id
* @property int $message_count
* @property int $alerts_unread
* @property int $conversations_unread
* @property int $register_date
* @property int $last_activity
* @property int $trophy_points
* @property int $avatar_date
* @property int $avatar_width
* @property int $avatar_height
* @property bool $avatar_highdpi
* @property string $gravatar
* @property string $user_state
* @property bool $is_moderator
* @property bool $is_admin
* @property bool $is_staff
* @property bool $is_banned
* @property int $like_count
* @property string $custom_title
* @property int $warning_points
* @property string $secret_key
* @property int $permission_combination_id_
* @property int $last_activity_
*
* GETTERS
* @property \XF\PermissionSet $PermissionSet
* @property bool $is_super_admin
* @property string $email_confirm_key
* @property int $warning_count
*
* RELATIONS
* @property \XF\Entity\Admin $Admin
* @property \XF\Entity\UserAuth $Auth
* @property \XF\Entity\UserConnectedAccount[] $ConnectedAccounts
* @property \XF\Entity\UserOption $Option
* @property \XF\Entity\PermissionCombination $PermissionCombination
* @property \XF\Entity\UserProfile $Profile
* @property \XF\Entity\UserPrivacy $Privacy
* @property \XF\Entity\UserBan $Ban
* @property \XF\Entity\UserReject $Reject
* @property \XF\Entity\SessionActivity $Activity
* @property \XF\Entity\ApprovalQueue $ApprovalQueue
* @property \XF\Entity\UserFollow[] $Following
*/
Obviously this was an open bug report so until we say otherwise there's every danger that we'd have implemented it (which we have for the next release).

You may still want to use your own version, though. Ours, by design, only adds class properties for the structure of the original class (so it bypasses structure extensions). There's a few other improvements in that it attempts to type hint getter function types and maintains the original column type if a getter overlaps it.
Typical. No matter, yours is better. I was just bored and wanted to see if I could do it ;)

Liam