### Setup Testing Environment Source: https://github.com/ppy/osu-web/blob/master/SETUP.md Copies example environment files and configures database and search index prefixes for testing. Ensure values differ from production. ```bash cp .env.testing.example .env.testing cp .env.dusk.local.example .env.dusk.local # Make sure to set ES_INDEX_PREFIX and all the databases to something other than production. ``` -------------------------------- ### Install Packages and Build Assets Source: https://github.com/ppy/osu-web/blob/master/SETUP.md Execute the build script to install Composer and Yarn dependencies and build project assets. This script handles both PHP and Node.js package management. ```bash # will also install composer and yarn ./build.sh ``` -------------------------------- ### Configure .env File Source: https://github.com/ppy/osu-web/blob/master/SETUP.md Copy the example .env file and edit it to configure application and database settings. Essential for setting up the environment. ```bash # copy the example file and edit the settings, the important ones are APP_* and DB_* cp .env.example .env vi .env ``` -------------------------------- ### Start a Specific Docker Service Source: https://github.com/ppy/osu-web/blob/master/SETUP.md Starts a single Docker service. Replace `` with the actual name of the service. ```bash docker compose start ``` -------------------------------- ### chat.start Source: https://github.com/ppy/osu-web/blob/master/resources/views/docs/_websocket_commands.md Send this command to the websocket to start receiving chat messages. ```APIDOC ## chat.start ### Description Send to the websocket to start receiving chat messages. ### Method Send ### Endpoint Websocket ### Request Body - **event** (string) - Required - Name of the event. ### Request Example ```json { "event": "chat.start" } ``` ``` -------------------------------- ### Cursor Structure Example Source: https://github.com/ppy/osu-web/blob/master/resources/views/docs/_structures/cursor.md This is an example of the Cursor structure returned in API responses. The values should be used in the next request to retrieve the following page of results. ```json { "_id": 5, "_score": 36.234 } // query string: cursor[_id]=5&cursor[_score]=36.234 ``` ```json { "page": 2 } // query string: cursor[page]=2 ``` -------------------------------- ### GithubUser JSON Example Source: https://github.com/ppy/osu-web/blob/master/resources/views/docs/_structures/github_user.md This is an example of the GithubUser data structure in JSON format. It includes fields for display name, GitHub URL, GitHub username, and user IDs. ```json { "display_name": "bdach", "github_url": "https://github.com/bdach", "github_username": "bdach", "id": 218, "osu_username": null, "user_id": null, "user_url": null } ``` -------------------------------- ### Basic Script Tag Source: https://github.com/ppy/osu-web/blob/master/tests/Libraries/Markdown/indexable_markdown_examples/html.md A simple script tag example. ```html ``` -------------------------------- ### Start Receiving Chat Messages via Websocket Source: https://github.com/ppy/osu-web/blob/master/resources/views/docs/_websocket_commands.md Send this command to the websocket to begin receiving chat messages. Ensure the websocket connection is established before sending. ```javascript webSocket.send(JSON.stringify({ event: 'chat.start' })); ``` -------------------------------- ### Mod Structure Example Source: https://github.com/ppy/osu-web/blob/master/resources/views/docs/_structures/mod.md This JSON structure represents a configured gameplay mod, including its acronym and settings. ```json { "acronym": "MU", "settings": { "inverse_muting": true, "mute_combo_count": 1, "affects_hit_sounds": false } } ``` -------------------------------- ### Run Static Assets Service Source: https://github.com/ppy/osu-web/blob/master/DEPLOYMENT.md Starts the static asset server using Nginx on port 8080. The default Nginx configuration can be overridden by mounting a custom configuration file. ```bash assets ``` -------------------------------- ### Start Docker Services in Background Source: https://github.com/ppy/osu-web/blob/master/SETUP.md Starts all defined Docker services in detached mode, running them in the background. ```bash bin/docker_dev.sh -d ``` -------------------------------- ### Run Docker Development Script Source: https://github.com/ppy/osu-web/blob/master/SETUP.md Execute the Docker development script to start the development environment. Ensure the repository folder is owned by the user running the command. ```bash bin/docker_dev.sh ``` -------------------------------- ### Imagemap BBCode with Multiple Links Source: https://github.com/ppy/osu-web/blob/master/tests/Libraries/bbcode_examples/imagemap_multi_first_invalid.base.txt This example demonstrates an imagemap with multiple defined clickable areas, each linking to a different URL. Each area is defined by its coordinates and the target URL. ```bbcode [imagemap] https://assets.ppy.sh/osu-web-test-resources/placeholder-1280x720.jpg 40 50 60 70 https://osu.ppy.sh/users/2 [/imagemap] ``` -------------------------------- ### Emphasis Tag Source: https://github.com/ppy/osu-web/blob/master/tests/Libraries/Markdown/indexable_markdown_examples/html.md An example of an emphasis tag. ```html inline ``` -------------------------------- ### Anchor Tag Source: https://github.com/ppy/osu-web/blob/master/tests/Libraries/Markdown/indexable_markdown_examples/html.md An example of an anchor (link) tag. ```html link ``` -------------------------------- ### Run Octane Service Source: https://github.com/ppy/osu-web/blob/master/DEPLOYMENT.md Starts the Octane service, which serves PHP over HTTP on port 8000. This command is typically run within a Docker container. ```bash octane ``` -------------------------------- ### Run Artisan Queue Worker Source: https://github.com/ppy/osu-web/blob/master/DEPLOYMENT.md Starts an Artisan queue worker to process jobs. Specify the queue name(s) and any additional options. Multiple queues can be processed by separating their names with commas. ```bash artisan queue:work --queue= ``` -------------------------------- ### Watch for Asset Changes Source: https://github.com/ppy/osu-web/blob/master/SETUP.md Starts webpack in watch mode to continuously recompile assets whenever source files are modified. ```bash yarn run watch ``` -------------------------------- ### Example Ranking Data Structure Source: https://github.com/ppy/osu-web/blob/master/resources/views/docs/_structures/rankings.md This JSON structure represents a typical response for ranking data, including user statistics and performance metrics. It details player counts, accuracy, and user information. ```json { "cursor": { }, "ranking": [ { "grade_counts": { "a": 3, "s": 2, "sh": 6, "ss": 2, "ssh": 3 }, "hit_accuracy": 92.19, "accuracy": 0.9219, "is_ranked": true, "level": { "current": 30, "progress": 0 }, "maximum_combo": 3948, "play_count": 228050, "play_time": null, "pp": 990, "global_rank": 87468, "ranked_score": 1502995536, "replays_watched_by_others": 0, "total_hits": 5856573, "total_score": 2104193750, "user": { "avatar_url": "/images/layout/avatar-guest.png", "country": { "code": "GF", "name": "French Guiana" }, "country_code": "GF", "cover": { "custom_url": null, "id": "3", "url": "http://osuweb.test/images/headers/profile-covers/c3.jpg" }, "default_group": "default", "id": 458402, "is_active": false, "is_bot": false, "is_online": false, "is_supporter": true, "last_visit": "2017-02-22T11:07:10+00:00", "pm_friends_only": false, "profile_colour": null, "username": "serdman" } } ], "total": 100 } ``` -------------------------------- ### CommentableMeta Object Example Source: https://github.com/ppy/osu-web/blob/master/resources/views/docs/_structures/commentable_meta.md This JSON represents the metadata of an object that can be commented on. It includes the object's ID, title, type, and URL. ```json { "id": 407, "title": "Clicking circles linked to increased performance", "type": "news_post", "url": "https://osu.ppy.sh/home/" } ``` -------------------------------- ### Initialize Database Source: https://github.com/ppy/osu-web/blob/master/SETUP.md Run this Artisan command to create the database. Ensure your .env file is configured correctly. ```bash php artisan db:create ``` -------------------------------- ### Initialize Test Database Source: https://github.com/ppy/osu-web/blob/master/SETUP.md Run this command to reset the database to an empty state for testing. Existing data will be dropped. ```bash APP_ENV=testing php artisan migrate:fresh --no-interaction ``` ```bash docker compose run --rm -e APP_ENV=testing php artisan migrate:fresh --no-interaction ``` -------------------------------- ### Generate API Documentation Source: https://github.com/ppy/osu-web/blob/master/SETUP.md Run this command to generate API documentation in HTML and Markdown formats, which will be saved in the `docs` folder. ```bash php artisan scribe:generate ``` -------------------------------- ### Build Docker Image Source: https://github.com/ppy/osu-web/blob/master/DEPLOYMENT.md Builds the Docker image for deployment. Ensure you replace ``, ``, ``, and `` with your specific values. The `GIT_SHA` build argument can be dynamically generated. ```bash docker build -f Dockerfile.deployment --tag : --build-arg --build-arg . ``` -------------------------------- ### Reset Database and Seed Sample Data Source: https://github.com/ppy/osu-web/blob/master/SETUP.md Rebuilds the database schema and populates it with sample data. Requires `OSU_API_KEY` in `.env` for beatmap seeding. ```bash php artisan migrate:fresh --seed ``` -------------------------------- ### Removed Emphasis Tag Source: https://github.com/ppy/osu-web/blob/master/tests/Libraries/Markdown/indexable_markdown_examples/html.md An example of an emphasis tag that is marked for removal. ```html removed ``` -------------------------------- ### Create Initial User via Tinker Source: https://github.com/ppy/osu-web/blob/master/SETUP.md Registers a new user with provided credentials using the `UserRegistration` library within `artisan tinker`. Requires database seeding to be completed first. ```php php artisan tinker >>> (new App\Libraries\UserRegistration(["username" => "yourusername", "user_email" => "your@email.com", "password" => "yourpassword"]))->save(); ``` -------------------------------- ### Run Artisan Migration Source: https://github.com/ppy/osu-web/blob/master/DEPLOYMENT.md Executes database migrations. Run the container with this command to apply any pending database schema changes. ```bash artisan migrate ``` -------------------------------- ### Spotlight JSON Structure Source: https://github.com/ppy/osu-web/blob/master/resources/views/docs/_structures/spotlight.md This JSON object represents the structure of a spotlight. It includes details like name, start and end dates, type, and mode-specific settings. ```json { "end_date": "2019-03-22T00:00:00+00:00", "id": 1, "mode_specific": false, "name": "Best spinning circles 2019", "start_date": "2019-02-22T00:00:00+00:00", "type": "yearly" } ``` -------------------------------- ### Clone osu-web Repository Source: https://github.com/ppy/osu-web/blob/master/SETUP.md Use this command to clone the osu-web project from GitHub. ```bash git clone https://github.com/ppy/osu-web.git ``` -------------------------------- ### Generate GIT_SHA Build Argument Source: https://github.com/ppy/osu-web/blob/master/DEPLOYMENT.md A sample command to generate the `GIT_SHA` build argument, combining the current date and time with the short Git commit hash. ```bash "$(date +"%Y%m%d-%H%M%S")-$(git rev-parse HEAD | cut -c1-7)" ``` -------------------------------- ### Connect via wscat Source: https://github.com/ppy/osu-web/blob/master/resources/views/docs/_websocket.md Use wscat to connect to the websocket endpoint and include authorization headers. This command-line tool is useful for quick testing and debugging. ```bash wscat -c "{notification_endpoint}" -H "Authorization: Bearer {{token}}" ``` -------------------------------- ### ScoreStatistics JSON Example Source: https://github.com/ppy/osu-web/blob/master/resources/views/docs/_structures/score_statistics.md This JSON object shows the structure of ScoreStatistics, where keys are hit result types and values are their counts. It is used for both user scores and perfect play calculations. ```json { "ok": 3, "great": 211, "ignore_hit": 56, "slider_tail_hit": 56 } ``` -------------------------------- ### Build Assets Manually Source: https://github.com/ppy/osu-web/blob/master/SETUP.md Compiles frontend assets using yarn. This is typically handled automatically by Docker during development. ```bash # build assets (should be done automatically if using docker) yarn run development ``` -------------------------------- ### Run Javascript Tests with Karma Source: https://github.com/ppy/osu-web/blob/master/SETUP.md Execute the Javascript test suite using Karma. Headless Chrome is required and is pre-installed in the Docker environment. ```bash yarn karma start --single-run ``` ```bash docker compose run --rm testjs ``` -------------------------------- ### Create Alias for Docker Compose Exec Source: https://github.com/ppy/osu-web/blob/master/SETUP.md Sets up a shell alias `p` for frequently used `docker compose exec php` commands, simplifying command execution. ```bash alias p='docker compose exec php /app/docker/development/entrypoint.sh' ``` ```bash p artisan tinker ``` -------------------------------- ### List Docker Services Source: https://github.com/ppy/osu-web/blob/master/SETUP.md Use this command to check the status of all running Docker services defined in the compose file. ```bash docker compose ps ``` -------------------------------- ### Configure Git for Line Endings and File Mode on Windows Source: https://github.com/ppy/osu-web/blob/master/SETUP.md Adjust Git configurations for line endings (lf) and file mode to false to handle potential issues on Windows systems. ```bash git config core.eol lf git config core.filemode false ``` -------------------------------- ### Generate OAuth Client for API Access Source: https://github.com/ppy/osu-web/blob/master/SETUP.md Creates a new OAuth client with password grant type, necessary for connecting external applications like osu!(lazer) to the API. ```bash php artisan passport:client --password ``` -------------------------------- ### Using 'Basic' Colour Palette with LESS Variables Source: https://github.com/ppy/osu-web/wiki/Colour-System Employ these LESS variables for the 'basic' colour palette when an additional splash of colour is needed. These colours are constant and do not change with the base hue. ```less @osu-colour-[colour]-[code] ``` -------------------------------- ### Build Object Structure Source: https://github.com/ppy/osu-web/blob/master/resources/views/docs/_structures/build.md Represents the structure of a build object, including its ID, version, user count, creation timestamp, and update stream information. ```json { "id": 5778, "version": "20210520.2", "display_version": "20210520.2", "users": 22059, "created_at": "2021-05-20T14:28:04+00:00", "update_stream": { "id": 5, "name": "stable40", "display_name": "Stable", "is_featured": true } } ``` -------------------------------- ### Basic Websocket Command Structure Source: https://github.com/ppy/osu-web/blob/master/resources/views/docs/_websocket_commands.md Websocket commands are JSON objects with an 'event' field specifying the action. ```json { "event": "some.event" } ``` -------------------------------- ### Run PHPUnit Tests Source: https://github.com/ppy/osu-web/blob/master/SETUP.md Execute the PHPUnit test suite. Regular PHPUnit arguments are supported for filtering or controlling test execution. ```bash bin/phpunit.sh ``` ```bash docker compose run --rm php test phpunit ``` ```bash bin/phpunit.sh --filter=Route --stop-on-failure ``` -------------------------------- ### Run Browser Tests with Laravel Dusk Source: https://github.com/ppy/osu-web/blob/master/SETUP.md Execute the browser automation tests using Laravel Dusk. Note that Dusk tests may leave behind data, requiring a database reinitialization. ```bash bin/run_dusk.sh ``` ```bash docker compose run --rm php test browser ``` -------------------------------- ### Run Artisan Commands in Docker Source: https://github.com/ppy/osu-web/blob/master/SETUP.md Prefix Artisan commands with 'docker compose run --rm php' to execute them within the PHP Docker container. ```bash docker compose run --rm php artisan ``` -------------------------------- ### Resynchronise All News Posts Source: https://github.com/ppy/osu-web/wiki/Useful-Commands Use this command to resynchronize all news posts. This is typically run via tinker. ```php tinker> NewsPost::syncAll() ``` -------------------------------- ### Using Base Colours with LESS Variables Source: https://github.com/ppy/osu-web/wiki/Colour-System Use these LESS variables to apply colours derived from the base hue. Ensure the variable name matches the design documentation. ```less @osu-colour-[code] ``` -------------------------------- ### Build Object Structure Source: https://github.com/ppy/osu-web/blob/master/resources/views/docs/_structures/build.md This snippet details the fields available within a build object, including their types and whether they are optional. It also outlines optional attributes that can be included in responses and the structure for build versions. ```APIDOC ## Build Object ### Fields Field | Type ----------------|----- created_at | [Timestamp](#timestamp) display_version | string id | integer update_stream | [UpdateStream](#updatestream)? users | integer version | string? youtube_id | string? ### Optional Attributes Field | Type | Notes ------------------|-------------------------------------|------ changelog_entries | [ChangelogEntry](#changelogentry)[] | If the build has no changelog entries, a placeholder is generated. versions | [Versions](#build-versions) |
### Versions Field | Type ---------|----- next | [Build](#build)? previous | [Build](#build)? ``` -------------------------------- ### ProfilePage Sections Source: https://github.com/ppy/osu-web/blob/master/resources/views/docs/_structures/user.md Lists the available sections for a user's profile page. ```markdown | Section | |-----------------| | me | | recent_activity | | beatmaps | | historical | | kudosu | | top_ranks | | medals | ``` -------------------------------- ### Set GITHUB_TOKEN Environment Variable Source: https://github.com/ppy/osu-web/blob/master/SETUP.md Set the GITHUB_TOKEN environment variable before running the Docker development script. This token is required for several website components and will be recorded in the app config. ```bash export GITHUB_TOKEN=ghs_... ``` -------------------------------- ### User Object Structure Source: https://github.com/ppy/osu-web/blob/master/resources/views/docs/_structures/user.md Represents a user with various properties like ID, username, and status. ```json { "id": 2, "username": "peppy", "profile_colour": "#3366FF", "avatar_url": "https://a.ppy.sh/2?1519081077.png", "country_code": "AU", "is_active": true, "is_bot": false, "is_deleted": false, "is_online": true, "is_supporter": true } ``` -------------------------------- ### Run Artisan Schedule Runner Source: https://github.com/ppy/osu-web/blob/master/DEPLOYMENT.md Executes scheduled Artisan commands. This command should be run at least every 10 minutes. ```bash artisan schedule:run ``` -------------------------------- ### User Object Fields Source: https://github.com/ppy/osu-web/blob/master/resources/views/docs/_structures/user.md Details the fields available in the User object, including their types and descriptions. ```markdown Field | Type | Description | ----------------| ------------------------- | ---------------------------------------------------------------------- | avatar_url | string | url of user's avatar | country_code | string | two-letter code representing user's country | default_group | string? | Identifier of the default [Group](#group) the user belongs to. | id | integer | unique identifier for user | is_active | boolean | has this account been active in the last x months? | is_bot | boolean | is this a bot account? | is_deleted | boolean | | | is_online | boolean | is the user currently online? (either on lazer or the new website) | is_supporter | boolean | does this user have supporter? | last_visit | [Timestamp](#timestamp)? | last access time. `null` if the user hides online presence | pm_friends_only | boolean | whether or not the user allows PM from other than friends | profile_colour | string? | colour of username/profile highlight, hex code (e.g. `#333333`) | username | string | user's display name ``` -------------------------------- ### Pull Latest Docker Images Source: https://github.com/ppy/osu-web/blob/master/SETUP.md Fetches the latest versions of all Docker images defined in the compose file. ```bash docker compose pull ``` -------------------------------- ### Using osu-hsla() as a fade() Workaround Source: https://github.com/ppy/osu-web/wiki/Colour-System When using CSS variables for colours, the `fade()` LESS function may not work as expected. Use `osu-hsla()` instead, providing the colour variable and an alpha value between 0 and 1. ```less color: osu-hsla(@osu-colour-b6, 0.5); ``` -------------------------------- ### Access MySQL Client within PHP Service Source: https://github.com/ppy/osu-web/blob/master/SETUP.md Runs an interactive MySQL client within the PHP service container for direct database access. ```bash docker compose run --rm php mysql ``` -------------------------------- ### User Optional Attributes Source: https://github.com/ppy/osu-web/blob/master/resources/views/docs/_structures/user.md Lists optional attributes that may be included in the User object response. ```markdown Field | Type | Notes ---------------------------|----- | ----- account_history | [User.UserAccountHistory](#user-useraccounthistory)[] | | active_tournament_banner | [User.ProfileBanner](#user-profilebanner)? | Deprecated, use `active_tournament_banners` instead. active_tournament_banners | [User.ProfileBanner](#user-profilebanner)[] | | badges | [User.UserBadge](#user-userbadge)[] | | beatmap_playcounts_count | integer | | blocks | | | country | | | cover | | | favourite_beatmapset_count | integer | | follow_user_mapping | integer[] | | follower_count | integer | | friends | | | graveyard_beatmapset_count | integer | | groups | [UserGroup](#usergroup)[] | | guest_beatmapset_count | integer | | is_restricted | boolean? | | kudosu | [User.Kudosu](#user-kudosu) | | loved_beatmapset_count | integer | | mapping_follower_count | integer | | monthly_playcounts | [UserMonthlyPlaycount](#usermonthlyplaycount)[] | | nominated_beatmapset_count | integer | | page | | | pending_beatmapset_count | | | previous_usernames | | | rank_highest | [User.RankHighest](#user-rankhighest)? | | rank_history | | | ranked_beatmapset_count | | | replays_watched_counts | | | scores_best_count | integer | | scores_first_count | integer | | scores_recent_count | integer | | session_verified | boolean | | statistics | [UserStatistics](#userstatistics) | | statistics_rulesets | UserStatisticsRulesets | | support_level | | | unread_pm_count | | | user_achievements | | | user_preferences | | | ``` -------------------------------- ### ChangelogEntry JSON Structure Source: https://github.com/ppy/osu-web/blob/master/resources/views/docs/_structures/changelog_entry.md This JSON object represents a changelog entry. It includes fields for repository information, type, title, and message content. Note the presence of optional fields like github_url and message_html. ```json { "id": null, "repository": null, "github_pull_request_id": null, "github_url": null, "url": "https://osu.ppy.sh/home/news/2021-05-20-spring-fanart-contest-results", "type": "fix", "category": "Misc", "title": "Spring is here!", "message_html": "

New seasonal backgrounds ahoy! Amazing work by the artists.

\n
", "major": true, "created_at": "2021-05-20T10:56:49+00:00" } ``` -------------------------------- ### Connect via Node.js WebSocket Source: https://github.com/ppy/osu-web/blob/master/resources/views/docs/_websocket.md Programmatically connect to the websocket endpoint using Node.js. This method requires the 'ws' package and supports custom headers for authentication. Browser WebSocket clients do not support header options. ```javascript // Requires nodejs with using ESM. // Browser WebSocket does not support header option. import WebSocket from 'ws'; const url = 'notification-endpoint'; const token = 'some-token'; const headers = { Authorization: `Bearer ${token}`}; const ws = new WebSocket(url, [], { headers }); ws.on('message', (buffer) => console.log(buffer.toString())); ``` -------------------------------- ### Team Data Structure Source: https://github.com/ppy/osu-web/blob/master/resources/views/docs/_structures/team.md Represents a team with its essential properties. The flag_url is optional. ```json { "flag_url": "https://assets.ppy.sh/teams/flag/1/b46fb10dbfd8a35dc50e6c00296c0dc6172dffc3ed3d3a4b379277ba498399f.png", "id": 1, "name": "example team", "short_name": "TEAM" } ``` -------------------------------- ### Execute Artisan Tinker in Existing PHP Container Source: https://github.com/ppy/osu-web/blob/master/SETUP.md Runs the `artisan tinker` command directly within the running PHP service container for faster interactive sessions. ```bash docker compose exec php /app/docker/development/entrypoint.sh artisan tinker ``` -------------------------------- ### ProfileBanner Object Structure Source: https://github.com/ppy/osu-web/blob/master/resources/views/docs/_structures/user.md Details the structure of a user's profile banner. ```markdown Field | Type | Description --------------|-------------|------------ id | integer | | tournament_id | integer | | image | string? | | image@2x | string? | | ```