Johnathan Raymaker
Specs for a Twitch Login Plugin For WordPress

Specs for a Twitch Login Plugin For WordPress

Below is a comprehensive overview (a “master specification”) of all the requirements we’ve gathered so far for your Twitch Login WordPress plugin. This should help you keep track of what the plugin does (or must do) and how all the features fit together.


1. General Plugin & Setup

  1. Plugin Name & Headers
    • Must include standard WordPress plugin headers (Plugin Name, Version, etc.) so WordPress recognizes it.
    • Example: /** * Plugin Name: Twitch Login * Plugin URI: https://example.com * Description: A plugin that enables WordPress login via Twitch OAuth, plus custom profile pages. * Version: 1.0.0 * Author: John * License: GPL2 */
  2. Directory Structure
    • Typically: twitch-login/ ├── twitch-login.php (main plugin file) ├── admin/ │ └── settings-page.php (admin settings for Client ID, Secret, Test connection) ├── includes/ │ ├── class-twitch-auth.php (handles OAuth) │ └── class-twitch-user.php (fetches user info from Twitch) ├── templates/ │ ├── login-button.php (shortcode display) │ └── profile-page.php (custom user profile page layout) ├── user_profile_page.php (logic for /profile/<username> rewrite, etc.) ├── assets/ │ ├── css/ │ │ └── twitch-login.css │ └── js/ │ └── twitch-login.js └── readme.txt
  3. Activation & Deactivation
    • On activation, flush rewrite rules (so /profile/username starts working).
    • On deactivation, flush rewrite rules again to remove them cleanly.

2. Twitch OAuth Integration

  1. Admin Settings Page
    • Located under Settings > Twitch Login.
    • Fields:
      • Twitch Client ID
      • Twitch Client Secret
    • Buttons:
      • Save Settings (stores client ID & secret in wp_options)
      • Test Connection (calls Twitch’s OAuth token endpoint with a client_credentials grant, verifies success/failure)
  2. Front-End Login Flow
    • A “Login with Twitch” button that redirects to Twitch’s OAuth 2.0 endpoint.
    • After successful auth, Twitch redirects back with a code.
    • The plugin exchanges the code for an access_token.
    • The plugin fetches the user’s email and other data (like profile_image_url) from Twitch.
    • If no WP user exists with that email, create one; otherwise link the Twitch ID to the existing user.
    • Log the user into WordPress automatically (via wp_set_auth_cookie).
    • During each login, refresh the user’s stored Twitch avatar (so if they update their avatar on Twitch, your plugin updates it locally).
  3. User Meta
    • The plugin stores, at minimum:
      • twitch_id (the user’s unique ID on Twitch)
      • tlw_twitch_avatar (the user’s avatar URL from Twitch)
      • Possibly tlw_profile_bio, tlw_profile_visibility, etc., for the profile page.

3. “Twitch Login/Logout” Menu Item

  1. Appearance > Menus Meta Box
    • Under “Add menu items,” a custom meta box labeled “Twitch Login/Logout.”
    • Admin can check a box and click “Add to Menu,” which inserts a placeholder link into the menu.
  2. Dynamic Toggle
    • A placeholder URL like #twitch_login_placeholder is stored in the database.
    • A filter on wp_nav_menu_objects checks if a menu item’s URL contains that placeholder:
      • If not logged in, change the link text to “Login with Twitch” and the URL to the Twitch OAuth start.
      • If logged in, change the link text to “Logout from Twitch” and the URL to wp_logout_url(...) (or any desired logout endpoint).
    • This allows the same menu item to act as a login or logout link, depending on the user’s state.

4. Custom User Profile Pages

  1. Rewrite for /profile/<username>
    • A rewrite rule so ^profile/([^/]+)/? routes to a custom query var (e.g. tlw_profile).
    • A template redirect loads a custom file (templates/profile-page.php) to render the user’s profile.
  2. Public/Private Visibility
    • Each user can toggle whether their profile is visible to others.
    • If “Private,” only the owner can view it; any other visitor sees a message (“This profile is private.”).
  3. Bio Field
    • A simple textarea on the profile page.
    • Owner can write or edit their bio.
    • Data is stored in user meta (tlw_profile_bio).
  4. Twitch Avatar Display
    • If a user has logged in with Twitch, you’ve stored tlw_twitch_avatar in their meta.
    • The profile page displays that avatar if it’s present.
    • If tlw_twitch_avatar is empty, maybe show a default avatar or nothing.
  5. Save Confirmation
    • When the owner updates their bio or toggles public/private, the “Save Profile” button does a quick visual flash (green) to confirm success.
  6. “Your profile’s status” Title
    • A small heading above the public/private radio buttons: “Your profile’s status.”
  7. Redirect WP’s “Edit Profile”
    • By default, the WP admin bar’s “Edit Profile” links to /wp-admin/profile.php.
    • Instead, hook into admin_bar_menu and replace that link with /profile/<username> for the currently logged-in user.

5. Detailed Feature List / Requirements

Below is a more linear breakdown of each required feature, as gleaned from the conversation and specifications:

  1. Plugin Setup & Registration
    • Must have correct WordPress plugin headers.
    • Must define activation/deactivation hooks to flush rewrites.
    • Must enqueue front-end assets (CSS/JS) as needed.
  2. Admin Settings (“Twitch Login Settings”)
    • Client ID: text field
    • Client Secret: text field
    • Test Connection button
    • If test is successful, show success message; otherwise show failure.
  3. Twitch OAuth Flow
    • Button or link initiates the OAuth 2.0 “Authorization Code” flow with Twitch.
    • Use scope user:read:email (and any additional scopes if needed).
    • Exchange code for access_token.
    • Fetch user’s info (at least email + profile_image_url).
    • If new user, create WP user with that email; if existing, link.
    • Log user in automatically.
    • Update or refresh the user’s avatar URL in user meta on every login.
  4. Shortcode or Widget (Optional)
  5. Menu “Twitch Login/Logout”
    • A custom meta box in Appearance > Menus.
    • If user is logged out, link says “Login with Twitch,” linking to OAuth.
    • If user is logged in, link says “Logout from Twitch,” linking to wp_logout_url(...).
  6. Profile Page
    • Rewrite: /profile/<username>
    • Template that shows:
      1. Username or display_name.
      2. Twitch Avatar if available.
      3. Bio (stored in user meta), editable by the owner only.
      4. Public/Private radio toggle labeled “Your profile’s status”.
    • If set to “private,” only the owner can view it. Others see “This profile is private.”
    • On successful save, the “Save Profile” button flashes green.
  7. Admin Bar “Edit Profile” Redirect
    • Instead of linking to wp-admin/profile.php, link to /profile/<username> for logged-in user.
  8. Default Meta Setup
    • On plugin activation, if a user’s tlw_profile_visibility is not set, default to public.
    • If a user’s tlw_twitch_avatar is not set, default to an empty string.
  9. Security & Best Practices
    • Use nonce checks in forms.
    • Sanitize user input (e.g. sanitize_textarea_field for the bio).
    • Store tokens and secrets securely (though ephemeral tokens for login are typically okay if not stored long-term).
    • If multiple roles or membership constraints, ensure only the profile owner can edit.
  10. Visual / UX Requirements
    • Minimal, modern layout on the profile page.
    • If saving the profile, give user feedback (green flash).
    • Button color normally matches Twitch brand purple (#9146FF), then reverts after the flash.

6. Implementation Tips

  • Merging Code: Make sure your final plugin keeps all the required parts:
    • The Twitch login code.
    • The custom profile code.
    • The menu meta box.
    • The admin bar hook.
  • Rewrite Rules: Always remember to flush rewrites (activate/deactivate plugin or save permalinks).
  • Testing:
    • Test with a brand-new user who logs in via Twitch.
    • Test with an existing user who logs in via Twitch.
    • Verify profile set to private vs public.
    • Confirm the “Test Connection” button on settings.
    • Confirm the WP admin bar link changes.
  • Avatar Refresh: Each time a user logs in via Twitch, the plugin fetches their current profile_image_url from the Helix API. If changed, it updates tlw_twitch_avatar.

7. Conclusion

This covers all major and minor requirements discussed:

  1. Twitch OAuth with user creation/linking.
  2. WP Admin Settings (Client ID/Secret, test).
  3. Appearance > Menus toggle item.
  4. Custom Profile Page at /profile/username
    • Bio, privacy toggle, avatar display, save feedback, “Your profile’s status” heading.
    • If private, block visitors who aren’t the owner.
  5. Admin Bar “Edit Profile” → custom page.
  6. Avatar Refresh on each Twitch login.

By following these specifications, your plugin will provide a seamless Twitch-based login, custom user profiles, a dynamic login/logout menu item, and user-friendly editing features.